iit-mcp-hudu 0.6.0 → 0.8.0

package/.env.example

@@ -106,16 +106,57 @@ LOG_LEVEL=info
 # hudu_read; the dedicated per-resource resolve tools are unaffected.
 # HUDU_SEARCH_RESOURCES=articles,assets,companies,users,groups,websites
 
-# Which body-index tier hudu_search uses: auto (answer from Hudu search now, build the body index in
-# the background), index (a call may wait for a complete body-index answer) or vendor (never build a
-# body index). Unset means the transport default: auto under http, index under stdio. Under http the
-# tier is policy, not a call parameter, so the served schema offers neither tier nor refresh.
+# Which body tier hudu_search uses: auto (answer from Hudu search now, build the body index in the
+# background), index (a call may wait for a complete body-index answer), typesense (search Hudu's
+# whole-corpus Typesense index -- needs the pair below) or vendor (never use a body tier). Unset means
+# the transport default: auto under http, index under stdio, and typesense under BOTH when the
+# Typesense pair is configured (it has no cold start, so the transport asymmetry does not apply).
+# Naming typesense without the pair is a startup error. Under http the tier is policy, not a call
+# parameter, so the served schema offers neither tier nor refresh.
 # HUDU_SEARCH_TIER_POLICY=auto
 
 # Body-index TTL in milliseconds (the SDK's indexTtlMs; default 600000, ten minutes). Beyond it, an
 # answer is marked stale and the next search rebuilds in the background.
 # HUDU_SEARCH_INDEX_TTL=600000
 
+# --- Typesense body tier (optional; both URL and key, or neither) -------------------------------
+#
+# Hudu's own Typesense index already holds the whole corpus (article bodies and asset custom-field
+# text), so this tier makes hudu_search body-complete without the in-memory index and its heap cap.
+# With the pair set, `typesense` becomes the default tier for `hudu_search`: the call reads the whole
+# corpus from Hudu's index instead of building a local body index. HUDU_SEARCH_TIER_POLICY=index or
+# vendor still overrides it; naming typesense without the pair fails boot.
+#
+# HUDU_TYPESENSE_URL is the ORIGIN only -- no path, no query. Three ways to reach it:
+#   LAN / VPN      : https://typesense.hudu.intellectit.com.au (source IP must be allow-listed)
+#   stdio anywhere : http://127.0.0.1:8108 with `ssh -L 8108:127.0.0.1:8108 <hudu-host>` running
+#   fixed egress IP: a public hostname, with that CIDR allow-listed on the Hudu host
+# HUDU_TYPESENSE_API_KEY is a SEARCH-ONLY key (`documents:search` on the two collections below).
+# Provisioning it is an ops step on the Hudu host; nothing in this server creates or rotates a key.
+#
+# Setting one without the other is a startup error. Leaving BOTH unset keeps today's behaviour
+# exactly: the in-memory body index, `HUDU_SEARCH_TIER_POLICY` as documented above, nothing else.
+# The key is never logged and never returned by a tool: only booleans and result codes leave the
+# process. `doctor` stays zero-wire and says nothing about this tier.
+# HUDU_TYPESENSE_URL=https://typesense.hudu.intellectit.com.au
+# HUDU_TYPESENSE_API_KEY=
+
+# Collection names, defaults Hudu's own. Keep them distinct; they name the index a search reads.
+# HUDU_TYPESENSE_ARTICLES_COLLECTION=articles
+# HUDU_TYPESENSE_ASSETS_COLLECTION=assets
+
+# Per-search deadline in milliseconds (default 4000, maximum 15000). A search has a vendor fallback,
+# so a longer wait is never the right trade; a value above the maximum fails boot.
+# HUDU_TYPESENSE_TIMEOUT_MS=4000
+
+# The credential re-read flag (default true). The SDK re-reads every Typesense hit through the Hudu
+# API under the CALLER's own credential before returning it; this repo only sets the flag. Set true
+# unless you are certain about the deployment: Hudu's index does not carry folder permissions and
+# keeps discarded articles, so with this false a hit can be a record the caller's Hudu permission
+# would hide, or one that was deleted.
+# SINGLE-TENANT, NON-RESTRICTED, READ-ONLY DEPLOYMENTS ONLY.
+# HUDU_TYPESENSE_VERIFY_HITS=true
+
 # Image tag docker-compose.yml builds and runs as. scripts/deploy.sh sets it to the git short SHA
 # of the deployed commit, so the running container is always tied to a commit and the previous
 # tag stays resolvable for rollback. Do not deploy by hand with it unset, and never tag :latest.

package/CHANGELOG.md

@@ -1,5 +1,93 @@
 # Changelog
 
+## 0.8.0
+
+**Upgrading from 0.7.0:** no configuration change for any existing deployment. Six new optional
+variables turn on a Typesense body tier; with both `HUDU_TYPESENSE_URL` and `HUDU_TYPESENSE_API_KEY`
+unset, the default tier, prose, the served tool schema, the doctor report, boot output and search
+results are byte-identical to the env-wiring head (#59, 41ad81e) — not to 0.7.0, whose `hudu_read`
+description differs; the frozen-surface test proves identity to that head only. node-hudu is pinned at
+0.21.0 (exact), which is the release
+that types `search.typesense` — the boundary cast the tier needed is gone.
+
+- Add: `HUDU_TYPESENSE_*` configure the optional Typesense body tier and the SDK client is built with
+  the resulting typed `search.typesense` block. The pair is set together or not at all: one without
+  the other fails boot naming both, the URL must be an http(s) origin (no path, query, fragment or
+  userinfo), the two collection names must differ, and the deadline is bounded at 15000 ms. The key
+  is never logged and never returned by a tool. `HUDU_TYPESENSE_VERIFY_HITS` accepts any case and
+  treats a blank as unset.
+- Add: optional **Typesense body tier**. It searches Hudu's own Typesense index, so article bodies
+  and asset custom-field text are covered for the WHOLE corpus instead of the in-memory index's
+  heap-capped slice. `HUDU_TYPESENSE_VERIFY_HITS` (default `true`) is the credential re-read flag:
+  the SDK re-reads every hit through the Hudu API under the caller's own credential, because Hudu's
+  index carries neither folder permissions nor deletions. This repo sets the flag (a test asserts it
+  reaches the client) and has not measured the re-read. `false` is documented as single-tenant,
+  non-restricted, read-only deployments only.
+- Add: `HUDU_SEARCH_TIER_POLICY` accepts `typesense`, and when the pair is configured the default
+  tier is `typesense` under **both** transports — the cold-start asymmetry `auto` exists for does
+  not apply to an index that is already built. Naming `typesense` without the pair is a startup
+  error, never a silent fallback, and so is naming it on an SDK build whose catalogue lacks the
+  probe operation. The corpus gate is renamed `bodySearchable` and now covers every body tier: when
+  `HUDU_SEARCH_RESOURCES` excludes articles or assets, the policy stays `vendor` and a request for
+  `index`, `auto` or `typesense` is refused, naming both body tiers.
+- Add: `hudu_get_api_info` reports `typesense: { configured, reachable, collections, probeMs }`
+  when the tier is configured (absent otherwise), from the SDK's one-request probe that a
+  search-only key may run; `error {code, message}` appears only when the probe could not answer, and
+  its code says which question failed — `NOT_IMPLEMENTED` (this SDK version has no probe),
+  `POLICY_DENIED` (the client's policy does not permit it), `PROBE_FAILED` (the call threw without a
+  string code, so the failure cannot be attributed) or the endpoint's own code. The tool
+  description names each field, and a test pins the exact emitted key set, because the output schema
+  keeps that field open (`z.unknown()`) to stay inside the `tools/list` byte budget. `doctor` stays zero-wire: it gains a config-shape row
+  (`configured`, `keyPresent`, `urlShapeOk`) only, and the row is absent when the tier is off.
+- Docs: `hudu_search` help names `meta.bodySource` (`index` | `typesense` | `none`) and all five
+  Typesense degraded reasons, grouped by what the operator must do — `typesense-unavailable`
+  (refused or timed out: check URL, tunnel, egress), `typesense-query-error` (the collection name or
+  query is wrong: Typesense answered 400/404/422, so the fix is `HUDU_TYPESENSE_*_COLLECTION` and
+  NOT an outage), `typesense-unauthorized` (key rejected), `typesense-hits-stale` (records still in
+  Hudu's index that this credential can no longer read: retry later or widen), and
+  `typesense-hits-unhydratable` (candidates unreadable for structural reasons — no company_id,
+  deleted layout, no usable id — so the data is the cause, not staleness). The staleness entry also
+  carries a stated LIMITATION: which answer Hudu returns for a permission-hidden record is
+  unverified upstream (that needs a live tenant). What is settled is the split — a 404 is a silent
+  stale drop (the record is genuinely gone), while a 403 is a surfaced read failure, so the answer
+  reports `complete: false` and names the resource in `meta.errors` and a hidden record is not folded
+  into staleness. Reported as a limitation, with no sixth degraded reason invented for it. The five strings live in
+  ONE exported literal (`TYPESENSE_DEGRADED_REASONS`, in the SDK's union order) that both the help
+  builder and the test read, so the prose cannot drift from the assertion; this server holds no
+  schema enum of its own for them. `degraded.reason` is passed through unchanged — a walk test feeds
+  each of the five, and a reason the server has never seen, and asserts the response and the text
+  carry them verbatim, because a rename here would break the pairing silently. The compact result
+  header states the body source. The tier sentence
+  names the corpus resolution where it states the policy: on a deployment that excludes articles or
+  assets, a configured Typesense tier is corpus-wide too, so the corpus gate resolves it to `vendor`
+  and the answer carries no body source. All of it is present only where the tier is configured, so
+  the unset surface stays byte-identical. README and `.env.example` document the six variables, the
+  reach modes (LAN, SSH tunnel, allow-listed egress) and the verification trade.
+- Add: the five reason strings live in ONE exported literal (`TYPESENSE_DEGRADED_REASONS`), and
+  `test/tools/typesense-tier.test.ts` compares that literal against the SDK's union at test time, in
+  order. The server does not compare at runtime: it prints the reason it receives verbatim. Counts
+  stay disclosures, never reasons.
+- Tests: config XOR both ways, defaults and every refusal branch, key never echoed; the block
+  reaching every SDK client and staying absent when unset; the default-tier matrix
+  (`configured`/`unset` x `stdio`/`http` x full/excluded corpus); the schema enum and the prose (only
+  when configured); `bodySource` header rendering; the api_info probe block and its emitted key set;
+  the doctor row without key material; the capability gate failing on a mock SDK without the probe;
+  the runtime enum comparison against the SDK's; and a documentation drift test derived from the
+  config schema rather than a hand-written list.
+
+## 0.7.0
+
+**Upgrading from 0.6.1:** no configuration change. The articles in the body index are now reserved their slots, so an account with many more assets than articles indexes every article instead of the freshest few: the 512 MiB write-enabled profile derives a 1,820-document cap against a larger article corpus and therefore indexes no assets at all (they stay searchable through Hudu's own title search). node-hudu is now 0.20.0, and `meta.index.docs.<resource>.capped` reports what the caps dropped. Serve over `http` with a 1 GiB container to index a whole midsize article corpus.
+
+- Fix: articles can no longer be crowded out of the body index by assets. node-hudu 0.20.0 adds `search.maxDocsByResource`, a hard reservation inside `maxDocs`; the server now names `articles` with the WHOLE document cap, so articles keep their slots (up to the cap) and assets fill whatever room is left, in `updated_at` order. MEASURED on the production tenant (19,991 assets + 3,204 articles = 23,195 documents): without a reservation the 21,845-document cap retained 19,991 assets and 1,854 of the 3,204 articles, so 1,350 articles had no index entry at all while asset rows (titles and custom fields, no long text) held 91% of the cap; 0.6.1's expectation that dividing the pool by two would keep every article was therefore false. With the cap reserved, that tenant's 21,845 documents hold all 3,204 articles and the remaining 18,641 asset slots (arithmetic from the SDK's reservation semantics, verified with a synthetic probe: 10 articles + 500 assets at a 100-document cap give 10 + 90, and 300 articles + 5 assets give 100 + 0). The asset share is derived and can be zero: assets keep `maxDocs - min(articles, maxDocs)` slots, so the 512 MiB write-enabled profile (a 1,820-document cap against 3,204 articles) indexes no assets and leans on Hudu's own title search for them. A quarter-reservation was rejected because a reservation is also a hard ceiling on the named resource (300 articles + 5 assets at a 100-document cap retained 30 documents with a quarter, 100 with the whole cap).
+- Chore: node-hudu 0.19.0 -> 0.20.0 (`server.json` `versionRange` 0.20.0). The SDK's other change also reaches us: `search.maxDocsByResource` is the only new option, and `meta.index.docs.<resource>.capped` (documents dropped per resource by the caps) now travels through `sanitizeIndexMeta` unchanged.
+
+## 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

@@ -31,7 +31,7 @@ four old names. Rows are compact summaries by default (id, name, key scalar fiel
 25-row assets page under 20,000 characters instead of ~88,000; pass `expand: true` for the full
 records (`hudu_read` `articles.list` rows are always full). Article rows carry no body unless expanded. Paging is unchanged (`asset_layouts` still takes no `page_size`).
 
-These tools run on node-hudu 0.19.0; the `SDK behaviour (0.12.0)` section below covers the behaviours that shape them: redirect refusal, the closed input contract, the error envelope, and the client opt-ins. Numeric ids must be positive integers on every tool; anything else is refused before a request is made.
+These tools run on node-hudu 0.20.0; the `SDK behaviour (0.12.0)` section below covers the behaviours that shape them: redirect refusal, the closed input contract, the error envelope, and the client opt-ins. Numeric ids must be positive integers on every tool; anything else is refused before a request is made.
 
 `hudu_fetch_many` (node-hudu 0.12.0) fetches up to 20 single records across mixed resources in
 one call: each item is exactly `{ resource, id, fields? }` — one of the 22 bare-id resources, a
@@ -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
@@ -275,15 +277,56 @@ which is exactly that knob's documented purpose. `meta.index` reports the index
 `stdio` the one long-lived index stays warm, both fields stay in the schema, and the default is
 `"index"`; a caller there can still pass `tier:"index"` for a complete first answer.
 
-`HUDU_SEARCH_TIER_POLICY=auto|index|vendor` sets that policy explicitly (default `auto` under
-`http`, `index` under `stdio`): `vendor` forces the vendor tier and never builds a body index,
-`index` lets a call wait for a complete body-index answer. When `HUDU_SEARCH_RESOURCES` excludes
-articles or assets the policy is `vendor` and no index path runs, whatever the variable says.
+`HUDU_SEARCH_TIER_POLICY=auto|index|vendor|typesense` sets that policy explicitly (default `auto`
+under `http`, `index` under `stdio`, and `typesense` under **both** when the Typesense pair is
+configured — it has no cold start, so the transport asymmetry does not apply): `vendor` forces the
+vendor tier and never uses a body tier, `index` lets a call wait for a complete body-index answer,
+`typesense` searches the whole corpus through Hudu's own index. Naming `typesense` without the pair
+fails boot. When `HUDU_SEARCH_RESOURCES` excludes articles or assets the policy is `vendor` and no
+body tier runs, whatever the variable says: every body tier is corpus-wide.
+
+A search answer also reports **which** body source produced it: `meta.bodySource` is `index`,
+`typesense` or `none`, and the compact header names it. `meta.degraded.reason` gains
+`typesense-unavailable` (the configured endpoint refused or timed out; the answer fell back to the
+local index or the vendor tier) and `typesense-unauthorized` (the key was rejected — the key is the
+thing to fix), so a body-blind answer always says why.
 `HUDU_SEARCH_INDEX_TTL` (milliseconds, default `600000`) is the body index's freshness window. What
 the SDK does past it — answer from the stale index while rebuilding in the background — is
 UNVERIFIED here: this repo sets the knob (a test asserts it reaches the client) but has not measured
 the stale-rebuild behaviour.
 
+`HUDU_TYPESENSE_*` configure the optional Typesense body tier — the same index Hudu's own UI
+searches, so body coverage does not depend on this process's heap:
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `HUDU_TYPESENSE_URL` | — | Origin only (`https://typesense.example.com`, or `http://127.0.0.1:8108` through an SSH tunnel). No path, query or fragment. |
+| `HUDU_TYPESENSE_API_KEY` | — | Search-only key (`documents:search` on the two collections). Never logged, never returned by a tool. |
+| `HUDU_TYPESENSE_ARTICLES_COLLECTION` | `articles` | Articles collection name. |
+| `HUDU_TYPESENSE_ASSETS_COLLECTION` | `assets` | Assets collection name; must differ from the articles one. |
+| `HUDU_TYPESENSE_TIMEOUT_MS` | `4000` | Per-search deadline; `15000` is the maximum and a larger value fails boot. |
+| `HUDU_TYPESENSE_VERIFY_HITS` | `true` | Re-read every hit through the Hudu API under the caller's credential (see below). |
+
+`HUDU_TYPESENSE_URL` and `HUDU_TYPESENSE_API_KEY` are set together or not at all: one without the
+other fails boot, naming both. With both set the server builds its SDK client with this block and
+the boot log gains one line, `typesense: enabled (collections articles, assets)` — the collections
+only, never the URL or the key. With both unset nothing changes, boot output included: no Typesense
+request is ever made.
+
+Setting the pair makes the `typesense` tier the default for `hudu_search`: the call reads the whole
+corpus directly from Hudu's index, with no local build. `HUDU_SEARCH_TIER_POLICY` still chooses the
+tier explicitly — `index` or `vendor` overrides that default, and naming `typesense` without the pair
+fails boot. The served schema advertises the `typesense` value only on a deployment that configured
+it.
+
+`HUDU_TYPESENSE_VERIFY_HITS` (default `true`) is the credential re-read flag. What the SDK does when
+it is on — re-read every candidate id through the Hudu API under the credential that made the call
+before returning a hit — is the SDK's behaviour: this repo sets the flag (a test asserts it reaches
+the client) and has not measured the re-read itself. Hudu's index carries neither folder permissions
+nor deletions (it keeps discarded articles), so the re-read is what stops a hit being a record the
+caller may not see. `false` skips it: faster, but a hit can be discarded or permission-hidden. Use
+`false` only on a single-tenant, non-restricted, read-only deployment.
+
 A request cancelled while a call waits on a body-index build answers instead of throwing.
 `meta.degraded.reason` stays `body-not-indexed` (the SDK's closed union), `meta.cancelled` records
 `{ during: "index-build", waited }` as a deliberate SERVER extension (the SDK's meta has no
@@ -298,7 +341,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 +351,70 @@ 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.
+
+ARTICLES ARE RESERVED THE WHOLE CAP. Without a reservation the SDK keeps the freshest `updated_at`
+across ALL resources, so on an account with more assets than articles the assets take every slot and
+the older articles have no index entry at all. `maxDocsByResource` (node-hudu 0.20.0) is a hard
+reservation inside `maxDocs`: the server names `articles` with the whole cap, which makes it
+articles-first — each article keeps its slot up to the cap, and assets fill whatever room is left,
+in the SDK's `updated_at` order. That is the resource split the index exists for: article rows carry
+the long text, asset rows do not.
+A smaller reservation would also be a hard ceiling on articles, so an article-heavy account would
+drop articles while its cap sat half empty (measured against the SDK: 300 articles and 5 assets at a
+100-document cap retain 30 documents with a quarter reserved and 100 with the whole cap; an
+asset-heavy corpus fills the cap either way).
+
+THE ASSET SHARE IS DERIVED, AND CAN BE ZERO: assets keep `maxDocs - min(articles, maxDocs)` slots.
+On the production corpus that is 18,641 of 21,845; where the article corpus meets or exceeds the cap
+the assets get none — the 512 MiB write-enabled profile derives a 1,820-document cap against 3,204
+articles, so `docs.assets.indexed` is 0 there and asset hits come from Hudu's own title/custom-field
+search, which every call runs. `meta.index.docs.<resource>.capped` (node-hudu 0.20.0) names the
+documents the caps dropped, per resource, so the loss is visible in the answer. The reservation
+tracks the cap,
+so it deepens with the heap like the rest of the budget: 17,408 article slots at a 1 GiB container's
+assumed ~816 MB heap ceiling, 21,845 at a 1024 MB one, 50,000 in a stdio parent. This is what the
+Unreleased CHANGELOG entry measures.
+
+MEASURED on the production tenant (19,991 assets + 3,204 articles = 23,195 documents). At the former
+division by eight (6,144 documents): 4,666 assets and 1,478 of the 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). Dividing the pool by two instead of eight
+was expected (INFERRED at the time) to keep all 3,204 articles at 17 MiB / 17,408 documents; the
+deployment measured that expectation FALSE — 15,588 assets and 1,820 articles — because the asset
+count fills whatever cap the pool offers. At the 21,845-document ceiling the split was 19,991 assets
+and 1,854 articles, i.e. 1,350 articles with no body index, while the asset rows (titles and custom
+fields, no long text) held 91% of the cap. Reserving the cap for articles is the fix: the same
+21,845-document cap then keeps all 3,204 articles and gives assets the remaining 18,641 slots (the
+SDK's reservation arithmetic, reproduced with a synthetic corpus in `test/index-reservation.test.ts`);
+`node-hudu` #122 has the upstream detail.
 
 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 +515,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
@@ -469,7 +556,7 @@ pnpm run dev
 
 CI (`.github/workflows/ci.yml`) runs `typecheck`, `lint` and `test` on every push and pull request.
 
-`node-hudu` is pinned to `0.19.0`. The catalog hash test detects metadata drift; upgrades require
+`node-hudu` is pinned to `0.20.0`. The catalog hash test detects metadata drift; upgrades require
 review of the client authority, operation enums and redaction regressions. Docker uses `pnpm install --frozen-lockfile`.
 
 ## Deployment

package/dist/config.js

@@ -43,9 +43,100 @@ export const SECRET_READ_POLICIES = ['deny', 'allow'];
  * `vendor` never builds an index at all. Unset means the transport default: `index` under `stdio`
  * (one long-lived credential, one warmed index) and `auto` under `http` (every caller's scope
  * starts cold, and a cold walk can outlast the consumer's call timeout).
+ *
+ * `typesense` answers the body search from Hudu's own Typesense index. It has no cold start, so it
+ * is the default under BOTH transports when `HUDU_TYPESENSE_URL` / `HUDU_TYPESENSE_API_KEY` are set
+ * — the transport asymmetry exists only for the in-memory walk. Naming it without that pair fails
+ * boot: a tier that cannot run must not be reachable by configuration typo.
+ */
+export const SEARCH_TIER_POLICIES = ['auto', 'index', 'vendor', 'typesense'];
+/**
+ * The registry key of the SDK operation the Typesense tier is built on (node-hudu#124).
+ *
+ * Exported because two very different questions read it: config asks whether this BUILD has it (a
+ * startup refusal), and the probe asks whether the live client may call it (a report field).
+ */
+export const BODY_PROBE_OPERATION = 'operations.probeBodySearch';
+/** The first node-hudu release that builds the probe operation. Named in the boot refusal. */
+export const MIN_NODE_HUDU_FOR_TYPESENSE = '0.21.0';
+/** A blank value is a copied `.env.example` placeholder, never a value: normalise it to unset. */
+function blankToUndefined(raw) {
+    return typeof raw === 'string' && raw.trim() === '' ? undefined : raw;
+}
+/**
+ * The Typesense body-search tier's fixed defaults. Of the knobs the design names, only the
+ * collection names, the deadline and the verification gate are environment-tunable.
+ *
+ * Two knobs are deliberately NOT here and NOT set by this server: the candidate count and the
+ * circuit-breaker window. They are the SDK's own calibrated values (DESIGN §3 WP-1) — 40 candidates
+ * and a 30 s cooldown at node-hudu 0.21.0 — and this server passes neither key, so the library's
+ * calibration applies and CANNOT be shadowed by a stale copy here. The intent is not left untested:
+ * `test/typesense-config.test.ts` reads the RESOLVED SDK config and asserts those two values, so a
+ * recalibration in a future node-hudu release fails a test and shows up in review instead of
+ * silently changing behaviour.
+ */
+export const TYPESENSE_DEFAULTS = {
+    /** Hudu's own collection names, so an operator who provisions a search-only key sets nothing. */
+    articlesCollection: 'articles',
+    assetsCollection: 'assets',
+    /** Whole-call deadline for one Typesense search request. */
+    timeoutMs: 4000,
+    /** Refused above this: one search must never become the slowest thing in a tool call. */
+    maxTimeoutMs: 15000,
+};
+/**
+ * Whether `url` is an http(s) ORIGIN: no path, query or fragment.
+ *
+ * The boot check in `loadConfig`'s refinement applies these rules with a per-cause message; this
+ * predicate is the one the zero-wire doctor reports on, so the two cannot disagree about "shape ok".
+ */
+export function isTypesenseOrigin(url) {
+    try {
+        const parsed = new URL(url);
+        return ((parsed.protocol === 'http:' || parsed.protocol === 'https:') &&
+            (parsed.pathname === '' || parsed.pathname === '/') &&
+            parsed.search === '' &&
+            parsed.hash === '');
+    }
+    catch {
+        return false;
+    }
+}
+/** Build the SDK block from an already-validated config. Never carries a value into a log sink. */
+export function typesenseSearchBlock(config) {
+    const url = config.HUDU_TYPESENSE_URL;
+    const apiKey = config.HUDU_TYPESENSE_API_KEY;
+    if (url === undefined || apiKey === undefined)
+        return undefined;
+    return {
+        url,
+        apiKey,
+        collections: {
+            articles: config.HUDU_TYPESENSE_ARTICLES_COLLECTION ?? TYPESENSE_DEFAULTS.articlesCollection,
+            assets: config.HUDU_TYPESENSE_ASSETS_COLLECTION ?? TYPESENSE_DEFAULTS.assetsCollection,
+        },
+        timeoutMs: config.HUDU_TYPESENSE_TIMEOUT_MS ?? TYPESENSE_DEFAULTS.timeoutMs,
+        // No `candidateLimit` and no `cooldownMs`: both are the SDK's calibration, and omission is what
+        // keeps this server from pinning a copy that silently overrides a future recalibration.
+        verifyHits: config.HUDU_TYPESENSE_VERIFY_HITS ?? true,
+    };
+}
+/**
+ * The one boot-time line describing the tier — `undefined` when it is off.
+ *
+ * Shape only: never the URL or the key, only the collection names the operator can already read in
+ * the environment. A disabled feature is INVISIBLE in boot output, because the byte-identical
+ * promise for unset deployments covers the log as well as the tool surface. Exported so a test can
+ * assert the line without booting a server.
  */
-export const SEARCH_TIER_POLICIES = ['auto', 'index', 'vendor'];
-/** Parse `HUDU_WRITE_ALLOW` once, here, so every consumer reads the same list. */
+export function describeTypesense(config) {
+    const block = typesenseSearchBlock(config);
+    if (block === undefined)
+        return undefined;
+    return `typesense: enabled (collections ${block.collections.articles}, ${block.collections.assets})`;
+}
+/**
+ * Parse `HUDU_WRITE_ALLOW` once, here, so every consumer reads the same list. */
 function parseAllowList(raw) {
     return (raw ?? '')
         .split(',')
@@ -171,6 +262,55 @@ const schema = z
      * background; a shorter value trades vendor-tier reads for fresher bodies.
      */
     HUDU_SEARCH_INDEX_TTL: z.coerce.number().int().positive().optional(),
+    /**
+     * The Typesense body-search endpoint: the origin only, e.g.
+     * `https://typesense.hudu.intellectit.com.au`, or `http://127.0.0.1:8108` through an SSH tunnel
+     * (DESIGN §7.3). No path, query or fragment — a Typesense base URL is an origin and a path there
+     * would silently point every search at nothing.
+     *
+     * Set together with {@link HUDU_TYPESENSE_API_KEY} or not at all: `loadConfig` refuses a
+     * half-configured pair, because a URL with no key is an unreachable tier and a key with no URL
+     * has nowhere to go. Both unset means the tier is off and the server behaves exactly as before.
+     */
+    HUDU_TYPESENSE_URL: z.preprocess(blankToUndefined, z.string().url('HUDU_TYPESENSE_URL must be an absolute URL, e.g. https://typesense.example.com').optional()),
+    /**
+     * The Typesense search-only key (`documents:search` on the two body collections). Never logged,
+     * never echoed in an error, never part of `doctor` output — a boolean and a probe result code
+     * are the only facts that leave the process.
+     */
+    HUDU_TYPESENSE_API_KEY: z.preprocess(blankToUndefined, z.string().min(1, 'HUDU_TYPESENSE_API_KEY must not be empty').optional()),
+    /** The articles collection name. Defaults to Hudu's own name; a rename is config, not code. */
+    HUDU_TYPESENSE_ARTICLES_COLLECTION: z.preprocess(blankToUndefined, z.string().min(1).optional()),
+    /** The assets collection name. Defaults to Hudu's own name. */
+    HUDU_TYPESENSE_ASSETS_COLLECTION: z.preprocess(blankToUndefined, z.string().min(1).optional()),
+    /**
+     * Whole-call deadline for one Typesense search, in milliseconds (default 4000).
+     *
+     * Bounded rather than free: a search has a vendor fallback, so waiting longer than a few seconds
+     * is always the wrong trade. Above {@link TYPESENSE_DEFAULTS.maxTimeoutMs} the container fails
+     * boot instead of accepting a value the tier was never designed for.
+     */
+    HUDU_TYPESENSE_TIMEOUT_MS: z.preprocess(blankToUndefined, z.coerce
+        .number()
+        .int()
+        .positive()
+        .max(TYPESENSE_DEFAULTS.maxTimeoutMs, `HUDU_TYPESENSE_TIMEOUT_MS must be at most ${TYPESENSE_DEFAULTS.maxTimeoutMs}; the tier has a vendor fallback and a search must not outlast the call`)
+        .optional()),
+    /**
+     * Whether every Typesense hit is re-read through the Hudu API under the caller's own credential
+     * before it is returned (default `true`).
+     *
+     * Hudu's index does not carry folder permissions and keeps discarded articles, so a raw hit is
+     * an unverified claim about a record this credential may not be allowed to see. `false` is
+     * faster and is documented as acceptable only for single-tenant, non-restricted deployments.
+     */
+    HUDU_TYPESENSE_VERIFY_HITS: z.preprocess(
+    // Same treatment as every other new knob: a blank placeholder is unset, and the value is
+    // matched case-insensitively so `TRUE` (a shell convention) is not a boot failure.
+    (raw) => {
+        const value = blankToUndefined(raw);
+        return typeof value === 'string' ? value.trim().toLowerCase() : value;
+    }, z.enum(['true', 'false']).optional().transform((value) => (value === undefined ? undefined : value === 'true'))),
     /**
      * The single switch for mutation. `deny` (the default) registers no `hudu_write` / `hudu_delete`
      * tool at all; `allow_list` and `all` register them and gate every call. Read effects are never
@@ -284,6 +424,89 @@ const schema = z
             }
         }
     }
+    // The Typesense pair is all-or-nothing. A URL with no key searches nowhere; a key with no URL
+    // has nowhere to go, and a key typed into the wrong deployment is a secret in the wrong place.
+    // Name BOTH variables in one message so the operator fixes the pair, not one guess at a time.
+    const typesenseUrl = c.HUDU_TYPESENSE_URL;
+    const typesenseKey = c.HUDU_TYPESENSE_API_KEY;
+    if ((typesenseUrl === undefined) !== (typesenseKey === undefined)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: [typesenseUrl === undefined ? 'HUDU_TYPESENSE_URL' : 'HUDU_TYPESENSE_API_KEY'],
+            message: 'HUDU_TYPESENSE_URL and HUDU_TYPESENSE_API_KEY must be set together or not at all: ' +
+                (typesenseUrl === undefined
+                    ? 'a key was set with no URL for it to reach (set HUDU_TYPESENSE_URL, or unset the key)'
+                    : 'a URL was set with no search key (set HUDU_TYPESENSE_API_KEY, or unset the URL to leave the Typesense tier off)'),
+        });
+    }
+    // The capability gate belongs HERE, with the rest of the boot refusals: a configured tier on an
+    // SDK build that cannot probe it would otherwise serve a default tier the SDK ignores while the
+    // prose claims Hudu's index answered — two contradictory stories in one process. Configuration
+    // that cannot run is a startup error, never a silent fallback.
+    if (typesenseUrl !== undefined && c.HUDU_TYPESENSE_API_KEY !== undefined && getCapability(BODY_PROBE_OPERATION) === undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['HUDU_TYPESENSE_URL'],
+            message: `HUDU_TYPESENSE_URL/HUDU_TYPESENSE_API_KEY are set, but this build of node-hudu has no ${BODY_PROBE_OPERATION}: the Typesense tier needs node-hudu >= ${MIN_NODE_HUDU_FOR_TYPESENSE}. Unset both variables, or upgrade node-hudu.`,
+        });
+    }
+    // An origin, not a URL. A scheme other than http/https is not a Typesense endpoint, and any
+    // path, query or fragment would be dropped or misapplied by a client that joins paths onto it —
+    // a silent wrong endpoint rather than a refused boot.
+    if (typesenseUrl !== undefined) {
+        let parsed;
+        try {
+            parsed = new URL(typesenseUrl);
+        }
+        catch {
+            parsed = undefined;
+        }
+        if (parsed === undefined || (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['HUDU_TYPESENSE_URL'],
+                message: 'HUDU_TYPESENSE_URL must be an http:// or https:// origin, e.g. https://typesense.example.com',
+            });
+        }
+        else if (parsed.username !== '' || parsed.password !== '') {
+            // Credentials in the URL would be sent to the vendor on every probe and would land in a log
+            // the moment anything printed the endpoint. Refused, and the message never repeats the value
+            // (it is a credential, and this is the one place it could leak by accident).
+            ctx.addIssue({
+                code: 'custom',
+                path: ['HUDU_TYPESENSE_URL'],
+                message: 'HUDU_TYPESENSE_URL must not carry credentials: put the key in HUDU_TYPESENSE_API_KEY, and never in the URL',
+            });
+        }
+        else if ((parsed.pathname !== '' && parsed.pathname !== '/') || parsed.search !== '' || parsed.hash !== '') {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['HUDU_TYPESENSE_URL'],
+                message: 'HUDU_TYPESENSE_URL must be an origin only: no path, query or fragment (e.g. https://typesense.example.com)',
+            });
+        }
+    }
+    // Two resources in one collection would make every hit ambiguous: an article id and an asset id
+    // are both bare numbers, and the caller's `resources` scope could not be honoured.
+    const articlesCollection = c.HUDU_TYPESENSE_ARTICLES_COLLECTION ?? TYPESENSE_DEFAULTS.articlesCollection;
+    const assetsCollection = c.HUDU_TYPESENSE_ASSETS_COLLECTION ?? TYPESENSE_DEFAULTS.assetsCollection;
+    if (articlesCollection === assetsCollection) {
+        ctx.addIssue({
+            code: 'custom',
+            path: [c.HUDU_TYPESENSE_ASSETS_COLLECTION === undefined ? 'HUDU_TYPESENSE_ARTICLES_COLLECTION' : 'HUDU_TYPESENSE_ASSETS_COLLECTION'],
+            message: `articles and assets must search different collections (both resolve to "${articlesCollection}"); set HUDU_TYPESENSE_ARTICLES_COLLECTION or HUDU_TYPESENSE_ASSETS_COLLECTION`,
+        });
+    }
+    // A tier that cannot run must not be reachable by configuration: naming `typesense` without the
+    // endpoint and key would otherwise degrade every search at the first call instead of failing
+    // the container once, at boot.
+    if (c.HUDU_SEARCH_TIER_POLICY === 'typesense' && typesenseUrl === undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['HUDU_SEARCH_TIER_POLICY'],
+            message: 'HUDU_SEARCH_TIER_POLICY=typesense requires HUDU_TYPESENSE_URL and HUDU_TYPESENSE_API_KEY; set both, or choose auto|index|vendor',
+        });
+    }
     // `HUDU_WRITE_ALLOW` is only meaningful under `allow_list`, where a bad list must fail the
     // container rather than a call six months later. Every problem is reported at once, on the one
     // error path `loadConfig` already owns.
@@ -325,6 +548,14 @@ const schema = z
         }
     }
 });
+/**
+ * Every `HUDU_TYPESENSE_*` knob the schema accepts, derived from the schema rather than retyped.
+ *
+ * The documentation-drift test reads THIS list: a knob added to the schema and forgotten in
+ * `.env.example` / the README then fails the test, which a hand-written list in the test could not
+ * catch — the test would have been asserting its own copy.
+ */
+export const TYPESENSE_ENV_NAMES = Object.keys(schema.shape).filter((name) => name.startsWith('HUDU_TYPESENSE_'));
 /**
  * Apply the same check to `HUDU_API_KEY` here as to the per-request key under `http`.
  *