feat(search): caller-owned content-search drain pool in SearchService

SearchService now owns a pool of drain threads that loop
vxcore_work_queue_process_next on the "vxcore.search" queue, powering vxcore's
caller-helps-drain content search (vxcore no longer owns a search thread pool).
Pool size is min(hardware_concurrency, 8), substituting 2 when the count is
unknown. Threads spawn after the worker thread starts and join in the dtor
BEFORE the mutex is deleted, while the vxcore context is still alive; idle
threads block on the queue condvar (~0 CPU) since the queue is pre-created.

- SearchCoreService::context() accessor for the drain loop.
- tests/core/test_search_service_drain: results-match-baseline, idle-no-spin,
  teardown-during-active-search (watchdog), cancel-with-backlog. Green.
- Docs: Search Threading Contract (root AGENTS.md) + SearchService drain pool
  (src/core/services/AGENTS.md) + vxcore Search backends note.
- Bumps libs/vxcore to the caller-owned vxcore.search WorkQueue commit.

Author: tamlok

AGENTS.md

@@ -501,6 +501,16 @@ The legacy `Buffer` (1-second timer in `src/core/buffer/buffer.cpp`) bypasses vx
 
 ---
 
+## Search Threading Contract
+
+Content search in vxcore owns NO thread pool. `vxcore_search_content` / `vxcore_search_content_ex` enqueue ONE work item per file onto a dedicated `"vxcore.search"` `WorkQueue` that is pre-created at `vxcore_context_create`. The CALLER's threads drain that queue, and the initiating thread help-drains its own enqueued items (caller-helps-drain: it loops `ProcessNext(5ms)` until the batch is done). VNote's [`SearchService`](src/core/services/searchservice.h) owns the drain pool that loops `vxcore_work_queue_process_next(ctx, "vxcore.search", 100)`. Batches under 50 files skip the queue and run inline sequentially.
+
+The initiating thread's self-drain is the correctness floor: a consumer that provides NO external drain threads still gets correct, single-threaded results, and extra drainers only add parallelism. Cancellation, `max_results`, and result ordering are preserved across both paths; an exception thrown mid-scan is caught and surfaces as `VXCORE_ERR_UNKNOWN`.
+
+This mirrors the vxcore/VNote ownership split used by sync: vxcore emits per-file search work as facts, VNote owns the drain policy. No vxcore-owned threads remain, the former `BS::thread_pool` search pool having been removed.
+
+---
+
 ## Code Style Guidelines
 
 ### Standards

libs/vxcore

@@ -115,3 +115,15 @@ The keychain PAT for a notebook is tied to its lifecycle. To avoid orphan vault
 | S6 startup sweep | `src/core/services/syncservice.cpp:1280` (`onMainWindowAfterStart`) | App start, for each notebook where `!isSyncEnabled(id) && m_credentialsStore->hasCredentials(id)` (disk says disabled but keychain still holds a PAT). Backstop for previous-session crashes between the JSON-clear and keychain-delete steps. | Disk and keychain already agree (normal case). |
 
 **Rule for new sync-related code paths**: any time you retire a notebook, roll back an enable, or transition to a state where the on-disk JSON no longer claims sync is enabled, route through one of the five sites above. Do not call `deleteCredentials` from controllers or widgets; the cleanup contract lives in `SyncService` (and the one historical exception in `NewNotebookController::bootstrapSync`, which is documented in `src/controllers/AGENTS.md`).
+
+## SearchService drain pool
+
+`SearchService` owns the pool of drain threads that empty vxcore's `"vxcore.search"` work queue (see the root [Search Threading Contract](../../../AGENTS.md#search-threading-contract)). vxcore owns no search threads; this pool is VNote's side of that contract.
+
+**Size.** `min(std::thread::hardware_concurrency(), 8)`, substituting `2` only when `hardware_concurrency()` returns `0` (count unknown). This is a fallback for the unknown case, not a floor: a genuine single-core host gets `1` drain thread. Each thread loops `vxcore_work_queue_process_next(ctx, "vxcore.search", 100)`.
+
+**Lifetime.** The drain threads are spawned in the `SearchService` constructor AFTER the worker thread has started, and torn down in the destructor by setting `m_stopDrain` and joining every drain thread BEFORE the queue mutex is deleted and while the vxcore context is still alive. Joining first prevents a drain thread from touching a half-destroyed queue or a freed context.
+
+**Idle cost.** Because the `"vxcore.search"` queue is pre-created at `vxcore_context_create`, idle drain threads block on the queue's condvar (~0 CPU). There is no busy-spin and no need to guard against a missing queue.
+
+**Degradation.** The initiating thread help-drains its own enqueued items, so a search stays correct even if this pool is absent or stalled. With no drain threads the search simply runs single-threaded; results, ordering, cancellation, and `max_results` are unaffected.

src/core/services/AGENTS.md

@@ -70,6 +70,10 @@ class SearchCoreService : public QObject, private Noncopyable {
   Error searchByTags(const QString &p_notebookId, const QString &p_queryJson,
                      const QString &p_inputFilesJson, QJsonArray *p_results) const;
 
+  // Non-owning access to the vxcore context (owned in main(), outlives services).
+  // Used by SearchService to drain the "vxcore.search" content-search work queue.
+  VxCoreContextHandle context() const { return m_context; }
+
 private:
   // Non-owning pointer to vxcore context.
   VxCoreContextHandle m_context = nullptr;

src/core/services/searchcoreservice.h

@@ -1,5 +1,7 @@
 #include "searchservice.h"
 
+#include <algorithm>
+
 #include <QDebug>
 #include <QJsonArray>
 #include <QJsonObject>
@@ -186,13 +188,37 @@ SearchService::SearchService(SearchCoreService *p_coreService, QObject *p_parent
   });
 
   m_thread->start();
+
+  unsigned n = std::thread::hardware_concurrency();
+  if (n == 0) {
+    n = 2;
+  }
+  n = std::min(n, 8u);
+
+  VxCoreContextHandle ctx = m_coreService->context();
+  for (unsigned i = 0; i < n; ++i) {
+    m_drainThreads.emplace_back([this, ctx]() {
+      while (!m_stopDrain.load(std::memory_order_relaxed)) {
+        if (vxcore_work_queue_process_next(ctx, "vxcore.search", 100) == 1) {
+          m_drainItemsProcessed.fetch_add(1, std::memory_order_relaxed);
+        }
+      }
+    });
+  }
 }
 
 SearchService::~SearchService() {
   cancel();
+  m_stopDrain.store(true, std::memory_order_relaxed);
   m_thread->quit();
   m_thread->wait();
 
+  for (auto &t : m_drainThreads) {
+    if (t.joinable()) {
+      t.join();
+    }
+  }
+
   delete m_mutex;
   m_mutex = nullptr;
 }

src/core/services/searchservice.cpp

@@ -2,7 +2,10 @@
 #define SEARCHSERVICE_H
 
 #include <atomic>
+#include <cstdint>
 #include <memory>
+#include <thread>
+#include <vector>
 
 #include <QMap>
 #include <QObject>
@@ -12,6 +15,8 @@
 #include <core/error.h>
 #include <core/searchresulttypes.h>
 
+#include <vxcore/vxcore.h>
+
 class QMutex;
 class QThread;
 
@@ -41,6 +46,11 @@ class SearchService : public QObject {
   bool isSearching() const;
   bool isSearching(int p_token) const;
 
+  size_t testDrainThreadCount() const { return m_drainThreads.size(); }
+  uint64_t testDrainItemsProcessed() const {
+    return m_drainItemsProcessed.load(std::memory_order_relaxed);
+  }
+
 signals:
   void searchFinished(int p_token, const SearchResult &p_result);
   void searchFailed(int p_token, const Error &p_error);
@@ -56,6 +66,10 @@ class SearchService : public QObject {
   QMap<int, std::shared_ptr<std::atomic<int>>> m_cancelFlags;
   QSet<int> m_activeTokens;
   int m_nextToken = 1;
+
+  std::vector<std::thread> m_drainThreads;
+  std::atomic<bool> m_stopDrain{false};
+  std::atomic<uint64_t> m_drainItemsProcessed{0};
 };
 
 } // namespace vnotex

src/core/services/searchservice.h

@@ -52,6 +52,20 @@ add_qt_test(test_searchresulttypes
   GUILESS
 )
 
+# T7 (search-drain-pool): SearchService owns a drain-thread pool that drains
+# vxcore's "vxcore.search" content-search work queue. Verifies (1) async
+# searchContent over a >50-file notebook matches the single-threaded baseline
+# result exactly, and (2) idle drain threads block on the condvar (0 items
+# processed across a 500ms idle window) with the pool sized min(hw,8) floor 2.
+add_qt_test(test_search_service_drain
+  SOURCES
+    test_search_service_drain.cpp
+  LINKS
+    core_services
+    vxcore
+  GUILESS
+)
+
 add_qt_test(test_searchresultmodel
   SOURCES
     test_searchresultmodel.cpp