vocs 2.4.0 → 2.5.2

package/dist/waku/internal/middleware/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/waku/internal/middleware/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACpD,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/waku/internal/middleware/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,uBAAuB,CAAA;AACjE,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACpD,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/waku/internal/middleware/index.js

@@ -1,3 +1,4 @@
+export { default as aiSearchWarmup } from './ai-search-warmup.js';
 export { default as mdRouter } from './md-router.js';
 export { default as redirects } from './redirects.js';
 export { default as trailingSlash } from './trailing-slash.js';

package/dist/waku/internal/middleware/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/waku/internal/middleware/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACpD,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/waku/internal/middleware/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,uBAAuB,CAAA;AACjE,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AACpD,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/waku/middleware.d.ts

@@ -1,7 +1,7 @@
 import * as middleware from './internal/middleware/index.js';
 export declare function middlewareModules(overrides?: Record<string, () => Promise<unknown>>): {
     [x: string]: (() => Promise<unknown>) | (() => Promise<{
-        default: typeof middleware.mdRouter | (() => import("hono").MiddlewareHandler) | ((options?: middleware.trailingSlash.Options) => import("hono").MiddlewareHandler);
+        default: (() => import("hono").MiddlewareHandler) | typeof middleware.mdRouter | (() => import("hono").MiddlewareHandler) | ((options?: middleware.trailingSlash.Options) => import("hono").MiddlewareHandler);
     }>);
 };
 //# sourceMappingURL=middleware.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vocs",
   "type": "module",
-  "version": "2.4.0",
+  "version": "2.5.2",
   "main": "./dist/index.js",
   "license": "MIT",
   "repository": {

package/src/cli.ts

@@ -117,12 +117,31 @@ cli
           case 'packed':
             console.log(`[vocs]   packed vectors (${event.dimensions}d, ${event.format})`)
             break
+          case 'sync:start':
+            console.log(`[vocs]   syncing ${event.chunks} chunks to the remote vector store...`)
+            break
+          case 'sync:progress': {
+            const now = Date.now()
+            if (event.done === event.total || now - lastFetchLog > 1000) {
+              lastFetchLog = now
+              console.log(`[vocs]   upserted ${event.done}/${event.total}`)
+            }
+            break
+          }
+          case 'synced':
+            console.log(
+              `[vocs]   synced (${event.upserted} upserted, ${event.skipped} unchanged, ${event.deleted} pruned)`,
+            )
+            break
         }
       },
     })
     const elapsed = ((Date.now() - started) / 1000).toFixed(1)
+    const remote = config._localRetriever?.vectorStore.target === 'remote'
     console.log(
-      `[vocs] AI search index built in ${elapsed}s (${manifest.vectorStore.count} chunks, ${manifest.vectorStore.dimensions}d, ${manifest.vectorStore.format}).`,
+      remote
+        ? `[vocs] AI search index synced in ${elapsed}s (${manifest.vectorStore.count} chunks, ${manifest.vectorStore.dimensions}d, remote vector store).`
+        : `[vocs] AI search index built in ${elapsed}s (${manifest.vectorStore.count} chunks, ${manifest.vectorStore.dimensions}d, ${manifest.vectorStore.format}).`,
     )
 
     // Persist to the canonical cache path so `vocs dev` can serve semantic

package/src/internal/retriever.test.ts

@@ -7,6 +7,7 @@ import * as ConfigSerializer from './config-serializer.js'
 import * as Embedding from './embedding.js'
 import * as Reranker from './reranker.js'
 import * as Retriever from './retriever.js'
+import * as VectorStore from './vector-store.js'
 
 const ctx = { basePath: '/' }
 
@@ -400,6 +401,20 @@ describe('resolveLocal (config split)', () => {
     expect(resolved?.private.chunking.maxCharacters).toBe(100)
     expect(resolved?.private.chunking.overlapCharacters).toBe(99)
   })
+
+  it('accepts a remote vector store (VectorStore.cloudflare)', () => {
+    const resolved = Retriever.resolveLocal(
+      {
+        embedding: Embedding.mock(),
+        vectorStore: VectorStore.cloudflare({ accountId: 'acc', apiToken: 'secret-token' }),
+      },
+      { basePath: '/' },
+    )
+    expect(resolved?.private.vectorStore.type).toBe('cloudflare')
+    expect(resolved?.private.vectorStore.target).toBe('remote')
+    // Adapter (and its credentials) stays in the private, never-serialized half.
+    expect(JSON.stringify(resolved?.public)).not.toContain('secret-token')
+  })
 })
 
 describe('config integration', () => {
@@ -643,8 +658,9 @@ describe('end-to-end (mock embedder)', () => {
         body: JSON.stringify({ query: 'installation' }),
       })
 
-    // First request returns immediately while the index builds in the background.
-    const first = await Retriever.handleSearchRequest(makeRequest(), config)
+    // First request returns immediately while the index builds in the background
+    // (`pendingWaitMs: 0` disables the grace wait to observe the 202).
+    const first = await Retriever.handleSearchRequest(makeRequest(), config, { pendingWaitMs: 0 })
     expect(first.status).toBe(202)
     const firstJson = (await first.json()) as { results: Retriever.Result[]; indexing: boolean }
     expect(firstJson.indexing).toBe(true)
@@ -659,6 +675,32 @@ describe('end-to-end (mock embedder)', () => {
     expect(Array.isArray(secondJson.results)).toBe(true)
   })
 
+  it('answers 202 when the build outlasts the grace wait', async () => {
+    const embedding = Embedding.from({
+      type: 'slow',
+      model: 'slow',
+      async embed() {
+        return new Promise(() => {}) as never // never resolves
+      },
+    })
+    const config = Config.define({
+      rootDir: dir,
+      ai: { retriever: Retriever.local({ embedding, cache: false }) },
+    })
+
+    const response = await Retriever.handleSearchRequest(
+      new Request('http://localhost/api/search', {
+        method: 'POST',
+        body: JSON.stringify({ query: 'installation' }),
+      }),
+      config,
+      { pendingWaitMs: 25 },
+    )
+    expect(response.status).toBe(202)
+    const json = (await response.json()) as { indexing: boolean }
+    expect(json.indexing).toBe(true)
+  })
+
   it('dev (NODE_ENV=development) loads the prebuilt index instead of building', async () => {
     const prev = process.env['NODE_ENV']
     process.env['NODE_ENV'] = 'development'
@@ -746,13 +788,11 @@ describe('end-to-end (mock embedder)', () => {
       })
     const options = { loadManifest: async () => manifest }
 
+    // The manifest loads within the grace wait, so the first request answers
+    // 200 directly instead of 202 (`indexing: true`).
     const first = await Retriever.handleSearchRequest(makeRequest(), config, options)
-    expect(first.status).toBe(202)
-    await Retriever.getServerIndex(config)
-
-    const second = await Retriever.handleSearchRequest(makeRequest(), config, options)
-    expect(second.status).toBe(200)
-    const json = (await second.json()) as { results: Retriever.Result[] }
+    expect(first.status).toBe(200)
+    const json = (await first.json()) as { results: Retriever.Result[] }
     expect(json.results.length).toBeGreaterThan(0)
     // Only the query was embedded — the index came from the bundled manifest.
     expect(purposes).toEqual(['query'])
@@ -803,8 +843,10 @@ describe('end-to-end (mock embedder)', () => {
         body: JSON.stringify({ query: 'installation' }),
       })
 
-    // First request kicks off the build and reports indexing.
-    expect((await Retriever.handleSearchRequest(makeRequest(), config)).status).toBe(202)
+    // First request kicks off the build and reports indexing (grace wait
+    // disabled — the fast failure would otherwise answer 503 directly).
+    const first = await Retriever.handleSearchRequest(makeRequest(), config, { pendingWaitMs: 0 })
+    expect(first.status).toBe(202)
     await expect(Retriever.getServerIndex(config)).rejects.toThrow('embedding unavailable')
 
     // Subsequent requests surface the failure and don't retrigger the build
@@ -854,3 +896,128 @@ describe('end-to-end (mock embedder)', () => {
     expect((await Retriever.handleSearchRequest(request, config)).status).toBe(400)
   })
 })
+
+describe('end-to-end (remote vector store)', () => {
+  let dir: string
+
+  beforeEach(() => {
+    Retriever._resetServerIndexCache()
+    dir = makeSite()
+  })
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true })
+  })
+
+  /** In-memory remote vector store (stands in for e.g. Cloudflare Vectorize). */
+  function memoryRemoteStore() {
+    const vectors = new Map<string, { metadata: Record<string, unknown>; vector: Float32Array }>()
+    const syncs: { count: number; dimensions: number }[] = []
+    const store: VectorStore.RemoteAdapter = {
+      type: 'memory',
+      target: 'remote',
+      async sync(entries, { dimensions }) {
+        syncs.push({ count: entries.length, dimensions })
+        vectors.clear()
+        for (const e of entries) vectors.set(e.id, { metadata: e.metadata, vector: e.vector })
+        return { deleted: 0, skipped: 0, upserted: entries.length }
+      },
+      async query(query, { topK }) {
+        return [...vectors.entries()]
+          .map(([id, v]) => {
+            let score = 0
+            for (let i = 0; i < query.length; i++) score += (v.vector[i] ?? 0) * (query[i] ?? 0)
+            return { id, metadata: v.metadata, score }
+          })
+          .sort((a, b) => b.score - a.score)
+          .slice(0, topK)
+      },
+    }
+    return { store, syncs, vectors }
+  }
+
+  function remoteConfig(store: VectorStore.RemoteAdapter, reranker?: Reranker.Adapter) {
+    return Config.define({
+      rootDir: dir,
+      ai: {
+        retriever: Retriever.local({
+          embedding: Embedding.mock({ dimensions: 64 }),
+          cache: false,
+          vectorStore: store,
+          ...(reranker ? { reranker } : {}),
+        }),
+      },
+    })
+  }
+
+  it('buildIndex syncs vectors remotely and emits no local artifact', async () => {
+    const { store, syncs, vectors } = memoryRemoteStore()
+    const config = remoteConfig(store)
+
+    const events: Retriever.ProgressEvent['type'][] = []
+    const manifest = await Retriever.buildIndex(config, {
+      onProgress: (event) => events.push(event.type),
+    })
+
+    expect(syncs).toEqual([{ count: vectors.size, dimensions: 64 }])
+    expect(vectors.size).toBeGreaterThan(0)
+    // Chunk metadata + vectors live remotely — the manifest is metadata-only.
+    expect(manifest.chunks).toEqual([])
+    expect(manifest.vectors.count).toBe(0)
+    expect(manifest.vectorStore.count).toBe(vectors.size)
+    expect(events).toContain('sync:start')
+    expect(events).toContain('synced')
+    expect(events).not.toContain('packed')
+  })
+
+  it('retrieves through the remote store', async () => {
+    const { store } = memoryRemoteStore()
+    const config = remoteConfig(store)
+    await Retriever.buildIndex(config)
+
+    const results = await Retriever.retrieveLocal(config, { query: 'embeddings cache build time' })
+    expect(results.length).toBeGreaterThan(0)
+    expect(results.some((r) => r.href.includes('/search'))).toBe(true)
+  })
+
+  it('applies the reranker to remote candidates', async () => {
+    const calls: { count: number; query: string }[] = []
+    const reranker = Reranker.from({
+      type: 'spy',
+      model: 'spy',
+      async rerank(query, documents, context) {
+        calls.push({ count: documents.length, query })
+        return documents.map((_, index) => ({ index, score: 0.5 })).slice(0, context.topK)
+      },
+    })
+    const { store } = memoryRemoteStore()
+    const config = remoteConfig(store, reranker)
+    await Retriever.buildIndex(config)
+
+    const results = await Retriever.retrieveLocal(config, { query: 'installation' })
+    expect(calls[0]?.query).toBe('installation')
+    expect(calls[0]?.count).toBeGreaterThan(0)
+    // Uniform reranker scores → the lexical title boost decides the winner.
+    expect(results[0]?.title).toBe('Installation')
+  })
+
+  it('serves search requests without an indexing phase', async () => {
+    const { store } = memoryRemoteStore()
+    const config = remoteConfig(store)
+    await Retriever.buildIndex(config)
+
+    // Even the first request answers 200 — remote mode has no in-process
+    // index to warm, so there is never a 202 `indexing` response.
+    const response = await Retriever.handleSearchRequest(
+      new Request('http://localhost/api/search', {
+        method: 'POST',
+        body: JSON.stringify({ query: 'installation' }),
+      }),
+      config,
+      { pendingWaitMs: 0 },
+    )
+    expect(response.status).toBe(200)
+    const json = (await response.json()) as { indexing: boolean; results: Retriever.Result[] }
+    expect(json.indexing).toBe(false)
+    expect(json.results.length).toBeGreaterThan(0)
+  })
+})

package/src/internal/retriever.ts

@@ -469,6 +469,12 @@ export declare namespace handleSearchRequest {
   type Options = {
     /** Source of the prebuilt manifest (e.g. baked into the server bundle). */
     loadManifest?: ManifestLoader | undefined
+    /**
+     * How long to wait for a pending index build before answering `202`.
+     *
+     * @default 1500
+     */
+    pendingWaitMs?: number | undefined
   }
 }
 
@@ -998,7 +1004,8 @@ export type IndexManifest = {
 /**
  * A build-progress event emitted by {@link buildIndex}, in pipeline order:
  * `documents` → (`sources:start` → `sources:progress`* → `sources:done`) →
- * `chunked` → `embed:start` → `embed:progress`* → `packed`.
+ * `chunked` → `embed:start` → `embed:progress`* → then `packed` (static
+ * store) or `sync:start` → `sync:progress`* → `synced` (remote store).
  */
 export type ProgressEvent =
   | { type: 'documents'; local: number }
@@ -1009,6 +1016,9 @@ export type ProgressEvent =
   | { type: 'embed:start'; cached: number; toEmbed: number; total: number }
   | { type: 'embed:progress'; embedded: number; toEmbed: number }
   | { type: 'packed'; dimensions: number; format: VectorStore.Format }
+  | { type: 'sync:start'; chunks: number }
+  | { type: 'sync:progress'; done: number; total: number }
+  | { type: 'synced'; deleted: number; skipped: number; upserted: number }
 
 export declare namespace buildIndex {
   type Options = {
@@ -1083,30 +1093,60 @@ export async function buildIndex(
   cache.save()
 
   const dimensions = vectors[0]?.length ?? priv.embedding.dimensions ?? 0
+  const embedding: IndexManifest['embedding'] = {
+    type: priv.embedding.type,
+    model: priv.embedding.model,
+    dimensions,
+    normalized: true,
+  }
+  const toMetadata = (c: Chunk): ChunkMetadata => ({
+    id: c.id,
+    href: c.href,
+    title: c.title,
+    titles: c.titles,
+    category: c.category,
+    type: c.type,
+    snippet: c.text.slice(0, 240),
+    text: c.text,
+    ...(c.weight !== undefined && c.weight !== 1 ? { weight: c.weight } : {}),
+  })
+
+  // Remote store: push vectors + metadata up instead of packing an artifact.
+  // The returned manifest carries build metadata only — chunks live remotely.
+  if (priv.vectorStore.target === 'remote') {
+    const store = priv.vectorStore
+    let synced: VectorStore.RemoteSyncResult = { deleted: 0, skipped: 0, upserted: 0 }
+    if (chunks.length > 0) {
+      onProgress?.({ type: 'sync:start', chunks: chunks.length })
+      const entries = chunks.map((c, i) => {
+        const vector = vectors[i]
+        if (!vector) throw new Error('[vocs] embedding produced no vector for a chunk')
+        return { id: c.id, metadata: toMetadata(c), vector }
+      })
+      synced = await store.sync(entries, {
+        dimensions,
+        onProgress: (done, total) => onProgress?.({ type: 'sync:progress', done, total }),
+      })
+    }
+    onProgress?.({ type: 'synced', ...synced })
+    return {
+      version: 1,
+      embedding,
+      vectorStore: { format: 'float32', count: chunks.length, dimensions },
+      chunks: [],
+      vectors: VectorStore.pack([], 'float32'),
+    }
+  }
+
   const format = VectorStore.resolveFormat(priv.vectorStore.format, priv.runtime)
   const packed = VectorStore.pack(vectors, format)
   onProgress?.({ type: 'packed', format, dimensions })
 
   return {
     version: 1,
-    embedding: {
-      type: priv.embedding.type,
-      model: priv.embedding.model,
-      dimensions,
-      normalized: true,
-    },
+    embedding,
     vectorStore: { format, count: chunks.length, dimensions },
-    chunks: chunks.map((c) => ({
-      id: c.id,
-      href: c.href,
-      title: c.title,
-      titles: c.titles,
-      category: c.category,
-      type: c.type,
-      snippet: c.text.slice(0, 240),
-      text: c.text,
-      ...(c.weight !== undefined && c.weight !== 1 ? { weight: c.weight } : {}),
-    })),
+    chunks: chunks.map(toMetadata),
     vectors: packed,
   }
 }
@@ -1247,6 +1287,13 @@ const serverIndexCache = new Map<string, ServerIndexEntry>()
 /** Minimum wait before a failed index build may be retried. */
 const failedBuildRetryMs = 30_000
 
+/**
+ * How long a search request waits for a pending index build before answering
+ * `202`. Matches the client's poll cadence, so a fast manifest load (the
+ * common cold-start case) answers on the first request instead.
+ */
+const pendingWaitMsDefault = 1_500
+
 function indexCacheKey(config: Config.Config, priv: LocalPrivateConfig): string {
   return `${config.rootDir}:${priv.embedding.type}:${priv.embedding.model}`
 }
@@ -1315,6 +1362,12 @@ async function resolveServerIndex(
   priv: LocalPrivateConfig,
   loadManifest?: ManifestLoader | undefined,
 ): Promise<ServerIndex> {
+  // Remote vector store: vectors live in the hosted database (synced at build
+  // time), so there is no in-process index to load — and never build one here,
+  // which would re-sync the store from a runtime instance.
+  if (priv.vectorStore.target === 'remote')
+    return { store: VectorStore.load(VectorStore.pack([], 'float32')), chunks: [] }
+
   // Baked-in manifest first (emitted into the server bundle at build time) —
   // serverless filesystems don't carry the cache directory or source pages, so
   // this is the only source that works everywhere.
@@ -1397,33 +1450,92 @@ function titleMatchBoost(queryTokens: readonly string[], title: string): number
   return queryTokens.length === titleTokens.length ? 0.25 : 0.12
 }
 
-/** Embeds the query, searches the local store, dedupes by href. */
-export async function retrieveLocal(
+/** Embeds and L2-normalizes a search query. */
+async function embedQuery(
+  priv: LocalPrivateConfig,
+  query: string,
+): Promise<Float32Array | undefined> {
+  const embedded = await priv.embedding.embed([query], { purpose: 'query' })
+  const raw = embedded[0]
+  return raw ? VectorStore.normalize(raw) : undefined
+}
+
+/** Maps remote-store metadata back into {@link ChunkMetadata} (skips malformed hits). */
+function chunkMetadataFromRemote(
+  metadata: Record<string, unknown> | undefined,
+): ChunkMetadata | undefined {
+  if (!metadata) return undefined
+  const href = str(metadata['href'])
+  const title = str(metadata['title'])
+  if (!href || !title) return undefined
+  const type = metadata['type']
+  return {
+    id: str(metadata['id']) ?? href,
+    href,
+    title,
+    titles: Array.isArray(metadata['titles'])
+      ? metadata['titles'].filter((t): t is string => typeof t === 'string')
+      : [],
+    category: typeof metadata['category'] === 'string' ? metadata['category'] : '',
+    type: type === 'page' || type === 'section' || type === 'nav' ? type : 'page',
+    snippet: typeof metadata['snippet'] === 'string' ? metadata['snippet'] : '',
+    ...(typeof metadata['text'] === 'string' ? { text: metadata['text'] } : {}),
+    ...(typeof metadata['weight'] === 'number' && metadata['weight'] !== 1
+      ? { weight: metadata['weight'] }
+      : {}),
+  }
+}
+
+/**
+ * Fetches vector candidates for a query — from the remote store (embed query →
+ * remote nearest-neighbor query) or the in-process static store (embed query →
+ * dot-product scan). `score` is the raw similarity; a reranker may replace it
+ * with a cross-encoder score.
+ */
+async function retrieveCandidates(
   config: Config.Config,
-  options: retrieveLocal.Options,
-): Promise<Result[]> {
-  const priv = requireLocal(config)
-  const limit = options.limit ?? priv.retrieval.topK
+  priv: LocalPrivateConfig,
+  queryText: string,
+): Promise<{ meta: ChunkMetadata; score: number }[]> {
+  if (priv.vectorStore.target === 'remote') {
+    const query = await embedQuery(priv, queryText)
+    if (!query) return []
+    const hits = await priv.vectorStore.query(query, { topK: priv.retrieval.candidateK })
+    return hits
+      .map((hit) => {
+        const meta = chunkMetadataFromRemote(hit.metadata)
+        return meta ? { meta, score: hit.score } : undefined
+      })
+      .filter((hit): hit is { meta: ChunkMetadata; score: number } => hit !== undefined)
+  }
+
   const index = await getServerIndex(config)
   // Empty index (dev with no prebuilt manifest): skip the query embedding call
   // and fall back to keyword-only search on the client.
   if (index.chunks.length === 0) return []
 
-  const embedded = await priv.embedding.embed([options.query], { purpose: 'query' })
-  const raw = embedded[0]
-  if (!raw) return []
-  const query = VectorStore.normalize(raw)
+  const query = await embedQuery(priv, queryText)
+  if (!query) return []
 
   const hits = VectorStore.search(index.store, query, priv.retrieval.candidateK)
-
-  // Vector candidates, paired with their chunk metadata. `score` is the raw
-  // similarity; a reranker (below) may replace it with a cross-encoder score.
-  let candidates = hits
+  return hits
     .map((hit) => {
       const meta = index.chunks[hit.index]
       return meta ? { meta, score: hit.score } : undefined
     })
     .filter((hit): hit is { meta: ChunkMetadata; score: number } => hit !== undefined)
+}
+
+/** Embeds the query, searches the vector store, dedupes by href. */
+export async function retrieveLocal(
+  config: Config.Config,
+  options: retrieveLocal.Options,
+): Promise<Result[]> {
+  const priv = requireLocal(config)
+  const limit = options.limit ?? priv.retrieval.topK
+
+  let candidates = await retrieveCandidates(config, priv, options.query)
+  if (candidates.length === 0) return []
 
   // Optional rerank: a cross-encoder reads each (query, passage) pair jointly
   // and re-scores the candidates for precision. On failure we keep the vector
@@ -1525,22 +1637,33 @@ async function handleLocalSearchRequest(
   const limit =
     typeof body.limit === 'number' ? Math.max(1, Math.min(20, Math.floor(body.limit))) : undefined
 
-  // Kick off (or reuse) the in-process index. This loads the prebuilt manifest
-  // when present and cold-builds otherwise — either way we never block the
-  // request: while pending, respond with `indexing: true` and let the client
-  // keep showing keyword results (and retry shortly). A failed build answers
-  // 503 (instead of 202) so the client stops polling; the entry is retried
-  // after a backoff.
-  const index = ensureServerIndex(config, options)
-  index.promise.catch(() => {}) // avoid unhandled rejection on the background build
-  if (index.status === 'error') return json({ error: 'Search failed' }, 503)
-  if (index.status === 'pending')
-    return json({ results: [], indexing: true }, 202, { 'Cache-Control': 'no-store' })
+  // Static store only: kick off (or reuse) the in-process index. This loads
+  // the prebuilt manifest when present and cold-builds otherwise. While
+  // pending, wait briefly — a manifest load (the common cold-start case)
+  // usually finishes within the grace window — then respond with
+  // `indexing: true` so the client keeps showing keyword results (and retries
+  // shortly). A failed build answers 503 (instead of 202) so the client stops
+  // polling; the entry is retried after a backoff.
+  //
+  // A remote store has no in-process index (vectors are queried in the
+  // database), so there is never an `indexing` phase.
+  let index: ReturnType<typeof ensureServerIndex> | undefined
+  if (config._localRetriever.vectorStore.target === 'static') {
+    index = ensureServerIndex(config, options)
+    index.promise.catch(() => {}) // avoid unhandled rejection on the background build
+    if (index.status === 'pending') {
+      const waitMs = options.pendingWaitMs ?? pendingWaitMsDefault
+      if (waitMs > 0) await Promise.race([index.promise.catch(() => {}), sleep(waitMs)])
+    }
+    if (index.status === 'error') return json({ error: 'Search failed' }, 503)
+    if (index.status === 'pending')
+      return json({ results: [], indexing: true }, 202, { 'Cache-Control': 'no-store' })
+  }
 
   try {
     const t0 = Date.now()
-    const [{ store }, results] = await Promise.all([
-      index.promise,
+    const [store, results] = await Promise.all([
+      index?.promise.then((i) => i.store),
       retrieveLocal(config, { query, limit }),
     ])
     const searchMs = Date.now() - t0
@@ -1551,7 +1674,7 @@ async function handleLocalSearchRequest(
       {
         results,
         indexing: false,
-        embedding: { type, model, dimensions: store.dimensions || dimensions },
+        embedding: { type, model, dimensions: store?.dimensions || dimensions },
         ...(reranker ? { reranker: { type: reranker.type, model: reranker.model } } : {}),
         timings: { searchMs },
       },
@@ -1586,6 +1709,14 @@ function json(data: unknown, status: number, headers?: Record<string, string>):
   })
 }
 
+/** Resolves after `ms` without holding the process open (Node-only `unref`). */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms)
+    ;(timer as unknown as { unref?: () => void }).unref?.()
+  })
+}
+
 function str(value: unknown): string | undefined {
   return typeof value === 'string' && value ? value : undefined
 }

package/src/internal/search.test.ts

@@ -667,7 +667,6 @@ Then do this.
           "title": "Step one",
           "titles": [
             "Getting Started",
-            undefined,
           ],
         },
         {
@@ -678,7 +677,6 @@ Then do this.
           "title": "Step two",
           "titles": [
             "Getting Started",
-            undefined,
           ],
         },
       ]

package/src/internal/search.ts

@@ -386,7 +386,8 @@ export function extract(source: string, config: Config.Config): extract.ReturnTy
 
         // Update title stack based on heading depth
         titleStack.length = depth - 1
-        const titles = [...titleStack]
+        // Skipped heading levels leave holes; drop them from the breadcrumb.
+        const titles = [...titleStack].filter((t) => t !== undefined)
         titleStack[depth - 1] = title
 
         currentSection = {