iit-mcp-hudu 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.6.1
+
+**Upgrading from 0.6.0:** no configuration change. Each scoped client's body index is deeper: a read-only http deployment gives one credential a third of the pool instead of an eighth. A write-enabled deployment on a small heap gets a shallower index than 0.6.0 (a ninth of the pool), because the eviction margin and the per-mode caches are both counted.
+
+- Fix: a read-only http deployment now gives each scoped client a THIRD of the pooled index text budget instead of an eighth (the pool is divided by two clients per cache plus one eviction of margin), so the body index is deep enough to search the articles it holds. MEASURED on the production tenant (2026-10-26) with the former division by eight at 1 GiB: a scope retained 4,666 assets and 1,478 of 3,204 articles; 1,036 article bodies were indexed, 317 had been evicted by the text budget and 3 truncated (the counts do not decompose the 1,478 — some retained articles carry no body text). The cause is the SDK's document cap, which keeps the freshest `updated_at` across ALL resources, so newer assets displaced older articles. A read-only deployment at a ~816 MB V8 ceiling now gets 17 MiB of text and 17,408 documents per scope instead of 6 MiB and 6,144 (INFERRED to keep all 3,204 articles and about 2,800 of their bodies, from the measured article density at 6,144; the SDK's cap is global, so this is an expectation, not a guarantee); a 512 MiB container gets 5.33 MiB and 5,461 instead of 2 MiB and 2,048. The document cap lost its 1,500-document floor and now follows the share (one document per KiB): the smallest pool with writes (an 8 MiB pool, 932,067 bytes per client) gets 910 documents instead of a 1,500-document cap above its own share. The pool is also divided by the number of per-mode caches: a read-only deployment creates one (`read`), a write-enabled deployment three (`read`, `write`, `delete`), because each mode entry keeps its own cache of scoped clients, and each cache's clients are counted with one extra eviction transient (the scope the LRU just dropped while an in-flight request finishes). So a write-enabled deployment gets 5.67 MiB and 5,802 per scope at ~816 MB, and a write-enabled 512 MiB container gets LESS than before (1.78 MiB and 1,820 instead of 2 MiB and 2,048) because the eviction margin is now counted, and in every profile the share is sized so the cache capacity (clients x caches) plus one eviction per cache stays within the pool; concurrent evictions beyond that margin can exceed it until their requests finish, because the SDK cannot revoke a live index. This also corrects a pre-existing oversubscription, since with eight shares three caches could hold 144 MiB of text against a 51 MiB pool. The trade is breadth for depth: at most two (origin, credential) pairs stay warm per mode cache, and a credential occupies one client per cache (read, plus write and delete when writes are enabled), so a deployment serving more credentials also loses each evicted scope's read-through TTL cache and re-fetches more from Hudu, and rebuilds an evicted index on demand (searches answer from the vendor tier meanwhile, unless `HUDU_SEARCH_TIER_POLICY=index` makes the call wait on that rebuild, with progress and cancellation), and a deployment needing both breadth and depth needs a larger heap. `MAX_SCOPED_CLIENTS` still equals `SCOPED_INDEX_BUDGET_DIVISOR` (now 2); the per-mode cache count (3: read, write, delete) is the second divisor, and `SCOPED_INDEX_EVICTION_TRANSIENT` (1) is added to the per-cache count before multiplying — it is a margin, not a third multiplicand.
+
 ## 0.6.0
 
 **Upgrading from 0.5.1:** under `MCP_TRANSPORT=http` the served `hudu_search` schema no longer offers `tier` or `refresh`, and the tier is server-side policy: `auto` by default, so a call answers from the vendor tier while the index builds. Set `HUDU_SEARCH_TIER_POLICY=index` for an http deployment that should wait. The body-index text budget and document cap are now derived from the process heap (a sixteenth of the V8 ceiling) instead of the SDK's 64 MiB / 50,000 defaults; no configuration change is needed. Under `stdio` the default tier stays `index` and both fields are still served.

package/README.md

@@ -158,8 +158,10 @@ gate on who can use it. It is only ever presented to the default
 `HUDU_BASE_URL`: a request that names some other origin and brings no key of its own gets no
 credential and fails closed, so a caller cannot aim the server's key at a host it controls. (A
 blank value, as a copied `.env.example` leaves it, is treated as unset.) Each (origin, credential)
-pair gets its own scoped client (its own search index) cached by the pair's hash and capped, so
-one caller's indexed article bodies can never answer another's search.
+pair gets its own scoped client (its own search index) cached by the pair's hash and capped — at most
+two pairs stay warm in EACH mode cache, so a credential occupies one client per cache (read, plus
+write and delete when writes are enabled) and a further scope rebuilds its index on demand — so one
+caller's indexed article bodies can never answer another's search.
 
 `HUDU_ALLOWED_BASE_HOSTS` (`http` only; required unless `HUDU_ALLOW_ANY_BASE_HOST=true`) restricts which origins a caller may name in
 `X-Hudu-Base-Url`: a comma-separated list of exact hostnames or `*.example.com` subdomain suffixes
@@ -298,7 +300,7 @@ surface headroom); the meta vocabulary is enforced by the tests that publish it
 
 The body index is bounded by TWO caps derived from the same heap estimate: a text budget and a
 document cap. The text budget is a SIXTEENTH of the process's V8 heap ceiling, clamped to 8-64 MiB;
-the document cap is one document per KiB of that budget (`maxDocs`), clamped to 1,500-50,000. Both
+the document cap is one document per KiB of that budget (`maxDocs`), capped at 50,000. Both
 travel the SDK's `search` options, so neither is an env knob. The divisor moved from 10 to 16 in
 round 11 because the tenth left no usable production margin (the arithmetic below).
 
@@ -308,28 +310,42 @@ of heap and died with `Reached heap limit` mid-search. It measured the ~90 MB ba
 4 bytes of index structures per byte of text ACTUALLY HELD, not per byte of budget: that index held
 ~41 MB of text out of its 64 MiB budget, and the peak reconciles as ~90 + 4 x 41 = ~254 MB. Read
 against the budget instead of the held text the same ratio would predict 90 + 4 x 64 = ~346 MB, which
-the trace never saw. A 512 MiB container (roughly a 259 MB heap ceiling) now gets a 16 MiB pool and
-2 MiB per scoped client. A standalone walk of a synthetic 25,000-asset / 3,300-article tenant through
+the trace never saw. A 512 MiB container (roughly a 259 MB heap ceiling) now gets a 16 MiB pool,
+divided THREE ways for one read-only cache (5.33 MiB per scoped client) or nine ways when writes are
+enabled, because read, write and delete each keep their own cache and each counts one eviction of
+margin (1.78 MiB per client). The division is an exact byte quotient, so no pool space is lost to
+rounding. The share is SIZED so the cache capacity plus one eviction of margin per cache fits the
+pool; it is not an enforced peak. A scope evicted by the LRU stays resident while an in-flight
+request that resolved it finishes, and because the SDK cannot revoke a live index, concurrent
+evictions of distinct credentials can exceed the pool until those requests settle. A standalone walk of a synthetic 25,000-asset / 3,300-article tenant through
 the real SDK client under a ~262 MB V8 ceiling (an uncommitted one-off probe; `--max-semi-space-size=1`
 brings V8's reported limit to ~262 MB, while `--max-old-space-size=259` alone reports ~451 MB in
 Node 24) peaked at ~136 MiB with the ROUND-10 tenth settings; the same walk with the OLD
 64 MiB / 50,000 settings peaked at ~147 MiB. Both survived. That probe's baseline is lower than the
-server's ~90 MB. A 1 GiB container's ~816 MB V8 ceiling — an ASSUMED ~80% container-to-heap ratio; the MEASURED ratio for the 512 MiB container is ~50.6% (259 MB) — gets a 51 MiB pool and 6 MiB per scoped client; a 1024 MB heap ceiling is what reaches the 64 MiB cap.
+server's ~90 MB. A 1 GiB container's ~816 MB V8 ceiling — an ASSUMED ~80% container-to-heap ratio; the MEASURED ratio for the 512 MiB container is ~50.6% (259 MB) — gets a 51 MiB pool and 17 MiB per scoped client (5.67 MiB with writes enabled); a 1024 MB heap ceiling is
+what reaches the 64 MiB cap.
 
 The document cap exists because the text budget bounds index TEXT only: a document whose text was
 evicted keeps its record and postings, the SDK's own default is 50,000 documents, and a walk can
 reach 250 pages x 100 rows x 2 body resources. Pairing the caps bounds that overhead — a 512 MiB
-container indexes up to 2,048 documents per scoped client (16,384 for the stdio pool), a 1 GiB
-container's ~816 MB ceiling (assumed ~80%) 6,144 per client (50,000 for the pool), and only a 1024 MB ceiling 8,192. The per-document cost is an ESTIMATE (~1 KB of record
+container indexes up to 5,461 documents per scoped client read-only, 1,820 with writes (a stdio
+parent carries the whole pool instead: 16,384 documents; writes enabled builds one parent per mode,
+so up to three of them carry it), a 1 GiB container's ~816 MB ceiling (assumed ~80%) 17,408 per
+client read-only, 5,802 with writes (50,000 in a stdio parent), and only a 1024 MB ceiling 21,845
+read-only, 7,281 with writes. The per-document cost is an ESTIMATE (~1 KB of record
 plus postings per document, on top of the text ratio), so the pair bounds growth without proving a
 peak. HONEST SCOPE: the SDK upserts every walked document and calls its cap only AFTER the walk, so
 `maxDocs` bounds the RETAINED index, not the build-time peak; the peak during a walk is bounded by
 the heap ceiling and the text budget's eviction, not by `maxDocs`. A capped index reports index state
-`partial`, exactly as it already does when the text budget bites. All ~3,300 articles of the
-production tenant fit at the 1 GiB figure; which documents the cap truncates first on a small heap is
-INFERRED, not measured: title-only assets are the expected first loss, because they cost a record
-without carrying text. The measured end-to-end walk kept 16,384 of 28,300 documents and never
-observed which ones went first.
+`partial`, exactly as it already does when the text budget bites. WHICH documents the cap keeps is
+the SDK's choice: the freshest `updated_at` across ALL resources, so assets can outrank older
+articles. MEASURED on the production tenant with the former division by eight (6,144 documents):
+4,666 assets and 1,478 of 3,204 articles retained; 1,036 article bodies indexed, 317 evicted by the
+text budget and 3 truncated (the counts do not decompose the 1,478 — some retained articles carry no
+body text). The same measurement is why a read-only scope now gets a THIRD of the pool instead of an
+eighth: 17 MiB and 17,408 documents at 1 GiB are expected (INFERRED, not measured at this division)
+to keep all 3,204 articles and about 2,800 of their bodies, while at 512 MiB (5,461 documents) 3,204
+articles leave only 2,257 slots for assets and the loss remains.
 
 BEFORE THE DIVISOR CHANGE. The round-10 end-to-end run measured the real server (`dist/main.js`) under
 a 259 MiB V8 ceiling: peak heapUsed 187.96 MB with a 24.6 MB baseline, so the INDEX STRUCTURES cost
@@ -430,7 +446,9 @@ Every client the server builds — the parent, the fail-closed placeholders and
   blindly.
 - `cache: 'recommended'` — fixed on: the
   per-entity read-through TTL preset (1 h structural / 5 min mutable / 1 min base). Caches are
-  per client, so per scope. The write and delete clients have their own caches, so after every `hudu_write` /
+  per client, so per scope — and a scope's client survives only while it stays in its mode cache,
+  which holds two pairs: a deployment serving more than two credentials therefore re-fetches more
+  from Hudu after an eviction, the same breadth-for-depth trade the body index makes. The write and delete clients have their own caches, so after every `hudu_write` /
   `hudu_delete` attempt that is not a dry run (including a failed or timed-out one, which may have
   applied) the server clears the read client's cache for the same scope: a record read (get, getSection, fetch_many, article context) after a write in
   the same server process is fresh. A write made by another process or deployment can still be served

package/dist/search-budget.js

@@ -7,12 +7,47 @@ export const MIN_INDEX_TEXT_BYTES = 8 * MIB;
 /** 64 MiB: the SDK's own default text bound, and the most a single scope should ever hold. */
 export const MAX_INDEX_TEXT_BYTES = 64 * MIB;
 /**
- * How many scoped clients share the pooled text budget (the cache cap in `tools/server.ts`).
+ * How many scoped clients ONE per-mode cache keeps warm (the cache capacity in `tools/server.ts`).
  *
  * The budget below is per PROCESS, and every scoped client materialises its own index, so the pool
- * must be divided by this number rather than handed to each client whole.
+ * must be divided rather than handed to each client whole — by this number, by the number of
+ * per-mode caches the factory builds (`read`, plus `write` and `delete` when writes are enabled),
+ * and by one eviction transient per cache.
+ *
+ * TWO, not eight, because a division by eight made the index shallower than the corpus it exists to
+ * search: on the production tenant at 1 GiB each scope got 6 MiB of text and 6,144 documents, and
+ * because the SDK's document cap keeps the freshest `updated_at` GLOBALLY (it has no per-resource
+ * cap), 4,666 newer assets displaced 1,726 of the 3,204 articles, leaving 1,036 article bodies
+ * indexed (MEASURED on the live server, 2026-10-26).
+ *
+ * RESULTING DEPTH: a read-only deployment (one cache, `HUDU_WRITE_POLICY=deny`) gives each scope
+ * 17 MiB and 17,408 documents at a ~816 MB ceiling; that is INFERRED to cover the tenant's article
+ * bodies almost entirely (about 2,800 of its 3,204 articles) and to keep all 3,204 articles, because
+ * the measured run retained articles at roughly a quarter of the freshest-document density. A
+ * write-enabled deployment has three caches, so the same pool is divided by nine and each scope gets
+ * 5.67 MiB and 5,802 documents.
+ *
+ * SIZED FOR, NOT ENFORCED: the share is the pool divided by `(capacity + 1) x caches`, where the +1
+ * leaves one eviction of margin per cache — the scope the LRU just dropped, which an in-flight
+ * request keeps alive until it finishes (`ScopedClientCache.for()`). That makes the steady-state
+ * bound `capacity x caches x share <= pool` hold, with one eviction per cache on top. It cannot
+ * enforce a peak: k distinct credentials arriving at once can each evict a different scope, and the
+ * SDK has no way to revoke a live index, so up to `capacity + k` scopes per cache can be alive at
+ * once. The pool is a sizing target, as it has been since #51, not a hard cap.
+ *
+ * This also CORRECTS a pre-existing oversubscription: with eight shares, three caches could hold
+ * 3 x 8 x 6 = 144 MiB of text against a 51 MiB pool. The trade is still breadth for depth: an
+ * evicted scope rebuilds on demand, and answers fall back to the vendor tier meanwhile — unless the
+ * deployment forces `HUDU_SEARCH_TIER_POLICY=index`, where the call waits on that rebuild (with
+ * progress and cancellation). A deployment needing both breadth and depth needs a larger heap.
  */
-export const SCOPED_INDEX_BUDGET_DIVISOR = 8;
+export const SCOPED_INDEX_BUDGET_DIVISOR = 2;
+/**
+ * One eviction of margin per cache: a scope evicted by the LRU stays reachable while an in-flight
+ * request that resolved it finishes, so the cache can briefly hold capacity + 1 shares. Concurrent
+ * evictions (k distinct credentials at once) can exceed this; see the divisor note.
+ */
+export const SCOPED_INDEX_EVICTION_TRANSIENT = 1;
 /**
  * The total extracted text the PROCESS's body indexes may hold, from the V8 heap ceiling in bytes.
  *
@@ -39,29 +74,47 @@ export const SCOPED_INDEX_BUDGET_DIVISOR = 8;
  * walk.
  *
  * POOL FRACTION: the budget is per PROCESS, not per client. Up to
- * {@link SCOPED_INDEX_BUDGET_DIVISOR} scoped clients stay warm and each owns a body index, so each is
- * handed only {@link scopedIndexTextBudgetBytes} (a whole-MiB share). The trade: several credentials
- * build shallower indexes (a scope that hits its share reports index state "partial"); needing depth
- * means raising the container memory or serving over stdio, where one credential owns the whole pool.
+ * {@link SCOPED_INDEX_BUDGET_DIVISOR} scoped clients stay warm in each per-mode cache and each owns a
+ * body index, so each is handed only {@link scopedIndexTextBudgetBytes}: the pool divided by
+ * ({@link SCOPED_INDEX_BUDGET_DIVISOR} clients + {@link SCOPED_INDEX_EVICTION_TRANSIENT} eviction of
+ * margin) times the number of caches. The trade: several credentials build shallower indexes (a
+ * scope that hits its share reports index state "partial"); needing depth means raising the
+ * container memory or serving over stdio, where the serving clients own the whole pool (one parent
+ * per mode there, so writes enabled can hold it in three parents; `hudu_search` uses the read one).
+ *
+ * MEASURED on the production tenant (2026-10-26), with the former division by eight: a scope retained
+ * 4,666 assets and 1,478 of 3,204 articles, indexed 1,036 article bodies, and had evicted 317 bodies
+ * by the text budget and truncated 3 (the counts do not decompose the 1,478: some retained articles
+ * carry no body text). The SDK's document cap keeps the freshest documents across ALL resources,
+ * which is the shallowness this divisor fixes.
  */
 export function indexTextBudgetBytes(heapLimitBytes) {
     const sixteenthInMib = Math.floor(heapLimitBytes / 16 / MIB) * MIB;
     return Math.min(MAX_INDEX_TEXT_BYTES, Math.max(MIN_INDEX_TEXT_BYTES, sixteenthInMib));
 }
 /**
- * The text budget for ONE scoped client: the process pool divided by the scoped-client cap.
+ * The text budget for ONE scoped client: the process pool divided by the clients the design expects
+ * it to fund — (cache capacity + one eviction of margin) x per-mode caches.
  *
- * A whole-MiB share with a 1 MiB floor, never above the pool itself (a pool smaller than the cap
- * would otherwise be oversubscribed). Small pools get a share below the single-client
- * {@link MIN_INDEX_TEXT_BYTES} on purpose — eight clients cannot each hold 8 MiB out of 16 MiB.
+ * `caches` is the number of scoped-client caches the process creates: 1 under
+ * `HUDU_WRITE_POLICY=deny` (read only), 3 otherwise (read, write, delete). It is required, not
+ * defaulted: a default of 1 would size every client for a read-only process and oversubscribe a
+ * write-enabled one threefold.
+ *
+ * The share is an exact byte quotient, so `clients x share` never exceeds the pool and no pool space
+ * is lost to rounding — whole-MiB rounding WOULD have discarded 7 of 16 MiB (44%) in the 512 MiB
+ * write-enabled profile, and up to 8 of 17 MiB in the worst case. Small pools get a share below the single-client
+ * {@link MIN_INDEX_TEXT_BYTES} on purpose — the clients cannot each hold the single-client floor out
+ * of an 8 MiB pool — and the SDK accepts any positive bound (a probe with 932,067 bytes built and
+ * answered `warm`).
  */
-export function scopedIndexTextBudgetBytes(heapLimitBytes) {
+export function scopedIndexTextBudgetBytes(heapLimitBytes, caches) {
     const total = indexTextBudgetBytes(heapLimitBytes);
-    const share = Math.floor(total / SCOPED_INDEX_BUDGET_DIVISOR / MIB) * MIB;
-    return Math.min(total, Math.max(MIB, share));
+    const clients = (SCOPED_INDEX_BUDGET_DIVISOR + SCOPED_INDEX_EVICTION_TRANSIENT) * Math.max(1, caches);
+    return Math.max(1, Math.floor(total / clients));
 }
-/** 1,500: a doc cap below this would truncate a small tenant's whole corpus, so a tiny budget keeps a floor. */
-export const MIN_INDEX_MAX_DOCS = 1500;
+/** 1: the cap follows the share's KiB count, so it never exceeds the text budget it is paired with. */
+export const MIN_INDEX_MAX_DOCS = 1;
 /** 50,000: the SDK's own default doc count, and the most one index should ever hold. */
 export const MAX_INDEX_MAX_DOCS = 50_000;
 /** ~1 KB of record + postings per indexed document, on top of the ~4x text ratio. ESTIMATE. */
@@ -81,22 +134,32 @@ const INDEX_DOC_BYTES = 1024;
  * reach 250 pages x 100 rows x 2 body resources, and a document whose text the budget evicted keeps
  * its record and postings, so the record overhead grows even when no text is added. This caps the
  * count from the same pool: ~1 KB of record + postings per document, i.e. one document per KiB of
- * text budget, clamped to 1,500-50,000.
+ * text budget, capped at 50,000 and never below one document.
  *
  * ESTIMATE, and it bounds growth rather than proving a peak: the pairing says "this index may hold X
  * MiB of text and Y documents", not "the process cannot exceed its heap". The SDK upserts every
  * walked document and applies the cap only AFTER the walk, so this bounds what the index RETAINS,
  * not the walk's peak (the heap ceiling and the text budget's eviction bound that). A capped index
- * reports index state "partial", as it already does when the text budget bites. Resulting numbers:
- * a 512 MiB container (MEASURED ~50.6% container-to-heap ratio: ~259 MB) gets a 16 MiB pool and 2 MiB
- * per scoped client, so 2,048 documents per scoped client (16,384 for the stdio pool); a 1 GiB
- * container's ~816 MB V8 ceiling — an ASSUMED ~80% ratio, not a measurement — gets a 51 MiB pool and
- * 6 MiB per client, so 6,144 documents (50,000 for the stdio pool), while a 1024 MB ceiling is what
- * reaches the 64 MiB cap and 8,192. All ~3,300 articles of the production tenant fit at the 1 GiB
- * figure. WHICH documents a small heap's
- * cap truncates first is INFERRED, not measured: title-only assets are expected to go first because
- * they cost a record without carrying text, but at 512 MiB the 2,048-document cap already sits below
- * the ~3,300 articles, so articles could be truncated first. The order is not measured.
+ * reports index state "partial", as it already does when the text budget bites. Resulting numbers,
+ * read-only profile / write-enabled profile (one cache / three caches):
+ * a 512 MiB container (MEASURED ~50.6% container-to-heap ratio: ~259 MB) gets a 16 MiB pool, so
+ * 5.33 MiB / 5,461 documents per scoped client read-only, 1.78 MiB / 1,820 with writes (a stdio
+ * parent carries the whole pool: 16,384 documents, and writes enabled builds one such parent per
+ * mode); a 1 GiB container's ~816 MB V8 ceiling — an ASSUMED ~80% ratio, not a measurement — gets a
+ * 51 MiB pool, so 17 MiB / 17,408 read-only, 5.67 MiB / 5,802 with writes (50,000 in a stdio parent);
+ * a 1024 MB ceiling reaches the 64 MiB cap, so 21.33 MiB / 21,845 read-only, 7.11 MiB / 7,281 with
+ * writes.
+ *
+ * WHICH documents the cap truncates is the SDK's choice, not this module's: it keeps the freshest
+ * `updated_at` across ALL resources, so assets can outrank older articles. MEASURED on the production
+ * tenant at the former division by eight (6,144 documents): 4,666 assets and 1,478 of the 3,204
+ * articles were retained; 1,036 article bodies were indexed, 317 had been evicted by the text budget
+ * and 3 truncated (the counts do not decompose the 1,478 — some retained articles carry no body
+ * text). At the 1 GiB read-only figures above (17 MiB and 17,408 documents) the measured article
+ * density (1,478 of the freshest 6,144) implies all 3,204 articles now fall inside the cap, so the
+ * article loss is expected to disappear (INFERRED, not measured at this division); at 512 MiB
+ * (5,461 documents) 3,204 articles would leave only 2,257 slots for assets, so the loss remains. The
+ * order is the SDK's.
  *
  * Named for its scoped use because that is where it matters: the pool is divided per client, and the
  * cap travels the same `search` object as `maxIndexTextBytes`.

package/dist/tools/search-policy.js

@@ -174,10 +174,13 @@ export function applySearchPolicyToInvoke(ctx, input) {
             throw configError(`hudu_read / hudu_write / hudu_delete: operations.searchKnowledge scope ${JSON.stringify(excluded)} is excluded by HUDU_SEARCH_RESOURCES; this deployment may search: ${searchableResources.join(', ')}. Use hudu_search, which applies the same policy.`);
         }
     }
-    // Under `http` the tier is deployment policy, so this path takes the same non-blocking route as
-    // `hudu_search`: a caller-supplied `tier` or `refresh` cannot make the call wait for a walk. That
-    // override is REPORTED, never silent: the dispatcher appends `tier-policy-override` to
-    // `meta.reasons` and a clause to the response text.
+    // Under `http` the tier is deployment policy, so this path takes the same server-side route as
+    // `hudu_search`: a caller-supplied `tier` or `refresh` cannot widen it. Whether that route waits
+    // for a corpus walk is policy, not the caller: `auto` (the default) answers from the index when
+    // it is warm and from the vendor tier while it builds, never waiting; `HUDU_SEARCH_TIER_POLICY=index`
+    // waits for a complete index on both paths. That override is
+    // REPORTED, never silent: the dispatcher adds `meta.policyOverride` (`{ stripped, appliedTier }`)
+    // and a clause to the response text.
     if (searchTierIsPolicy) {
         return {
             bag: { ...input, opts: { ...opts, scope, tier: toolDefaultTier, refresh: false } },

package/dist/tools/server.js

@@ -22,12 +22,13 @@ import { slimToolSchemas } from './slim.js';
 const SERVER_NAME = 'iit-mcp-hudu';
 const SERVER_VERSION = createRequire(import.meta.url)('../../package.json').version;
 /**
- * The maximum number of per-(origin, credential) scoped clients kept warm in one process.
+ * The maximum number of per-(origin, credential) scoped clients ONE mode cache keeps warm in a process.
  *
  * Each scoped client owns its own Hudu knowledge index. An unbounded map would let enough distinct
  * callers grow the heap past the container limit, so the cache is capped and evicts
- * least-recently-used first. The cap is the same number the process-wide index text budget is
- * divided by (`search-budget.ts`), so eight clients share one pool instead of each claiming it.
+ * least-recently-used first. The cap is the per-cache client count the process-wide index text
+ * budget is divided by (`search-budget.ts`); the factory builds one such cache per mode entry, and
+ * the budget is divided by that count too, so the caches together stay inside the pool.
  */
 export const MAX_SCOPED_CLIENTS = SCOPED_INDEX_BUDGET_DIVISOR;
 /**
@@ -404,7 +405,11 @@ export function createMcpServerFactory(requested, log) {
         // The body index's text budget follows the process's own heap ceiling, so a small container
         // reports index state "partial" instead of dying at the V8 heap limit (#51). This value is the
         // PROCESS-wide pool: the scoped clients below each take a share of it, since each materialises
-        // its own index. The parent client keeps the pool because under `stdio` it is the only client.
+        // its own index. The parent keeps the pool because under `stdio` it is the serving client and
+        // depth is the point of serving that way; with writes enabled there is one parent per mode
+        // (`read`, `write`, `delete`), so a raw `operations.searchKnowledge` invoked through the write or
+        // delete parent could build a second full-pool index (the `hudu_search` path uses the read
+        // parent only).
         // HUDU_SEARCH_INDEX_TTL, when set, is the body index's TTL (the SDK default is 10 minutes).
         search: {
             maxIndexTextBytes: poolTextBytes,
@@ -443,11 +448,17 @@ export function createMcpServerFactory(requested, log) {
                 ? [...reads, ...config.HUDU_WRITE_ALLOW.filter((key) => getCapability(key)?.effect === (mode === 'delete' ? 'destructive' : 'write')).flatMap((key) => withWriteDependencies(key, mode === 'delete' ? 'destructive' : 'write'))]
                 : undefined;
         const scopedOptions = { ...options, mode, reveal: false, ...(allowOperations ? { allowOperations } : {}) };
-        // ONE scoped client's share of the process pool: the cache can hold MAX_SCOPED_CLIENTS of them,
-        // so handing each the whole pool would let the process hold 8x the text it was sized for (#51).
+        // ONE scoped client's share of the process pool: each per-mode cache holds MAX_SCOPED_CLIENTS
+        // clients plus one eviction transient, and the process builds one cache per mode (`modes`,
+        // below), so handing each the whole pool would let it hold that many times the text it was
+        // sized for (#51). Divide by both factors, using the cache count the policy implies rather than
+        // how many are warm.
         // Only the per-(origin, credential) clients are divided — the parent keeps the pool, because
-        // under `stdio` it is the only client and a deeper index is the point of serving that way.
-        const scopedTextBytes = scopedIndexTextBudgetBytes(heapLimitBytes);
+        // under `stdio` it is the serving client and a deeper index is the point of serving that way
+        // (one parent per mode there, so up to three pool-sized clients with writes enabled; the
+        // `hudu_search` path uses the read parent only).
+        const indexCaches = modes.length;
+        const scopedTextBytes = scopedIndexTextBudgetBytes(heapLimitBytes, indexCaches);
         const scopedSearch = { ...options.search, maxIndexTextBytes: scopedTextBytes, maxDocs: scopedIndexMaxDocs(scopedTextBytes) };
         const parent = config.MCP_TRANSPORT === 'stdio'
             ? new HuduClient({ ...scopedOptions, apiKey: config.HUDU_API_KEY })
@@ -475,8 +486,14 @@ export function createMcpServerFactory(requested, log) {
             scopes: new ScopedClientCache((baseUrl, apiKey) => new HuduClient({ ...scopedOptions, baseUrl, apiKey, blockPrivateHosts: true, search: scopedSearch }), MAX_SCOPED_CLIENTS, log),
         };
     };
-    const read = build('read');
-    const mutations = config.HUDU_WRITE_POLICY === 'deny' ? undefined : { write: build('write'), delete: build('delete') };
+    // The per-mode caches this factory builds. ONE list drives both the caches built and the pool
+    // division (`indexCaches` above), so a change to the policy mapping cannot leave the budget
+    // describing a different number of caches than the process creates.
+    const writeModes = config.HUDU_WRITE_POLICY === 'deny' ? [] : ['write', 'delete'];
+    const modes = ['read', ...writeModes];
+    const built = new Map(modes.map((mode) => [mode, build(mode)]));
+    const read = built.get('read');
+    const mutations = writeModes.length === 0 ? undefined : { write: built.get('write'), delete: built.get('delete') };
     return (ctx) => {
         const resolve = (entry) => resolveHuduClient(entry, config, ctx, log);
         // Per serving unit (one stdio connection, or one HTTP request): the anomalies of the credential

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iit-mcp-hudu",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "MCP server for Hudu IT documentation, built on the node-hudu SDK",
   "license": "MIT",
   "author": "Max Soukhomlinov",