iit-mcp-hudu 0.6.1 → 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,87 @@
 # 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.

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
@@ -277,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
@@ -337,15 +378,43 @@ plus postings per document, on top of the text ratio), so the pair bounds growth
 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. 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.
+`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
@@ -487,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`.
  *

package/dist/doctor.js

@@ -1,3 +1,20 @@
+/**
+ * doctor.ts — the zero-wire credential/config preflight.
+ *
+ * The problem it solves is the expensive one: today the only way to confirm that a credential
+ * loaded intact is to dial Hudu, and against a vendor account where repeated auth failures risk a
+ * lock (2026-10-07 Autotask incident) that confirmation is the most expensive call the deployment
+ * can make. `doctor` answers the same question — "is the value I loaded shaped like the credential
+ * the vendor issued, and is it aimed at the origin I meant?" — from the process's own environment,
+ * with ZERO vendor requests, by construction: this module imports no Hudu client and reads no
+ * network, so there is nothing it could dial even if a value invited it.
+ *
+ * It reports shape, never value: a length, a two-character prefix and which anomalies were seen.
+ * The contract it feeds (README / `.env.example`): run `doctor` before a live session — a green
+ * doctor means any later 401 is vendor-side (rotated, revoked or role-restricted key), not a
+ * mangled load.
+ */
+import { isTypesenseOrigin, typesenseSearchBlock } from './config.js';
 import { describeCredential } from './credential.js';
 /** Check one credential-shaped value without ever carrying it out of this function. */
 function credentialCheck(name, value, required) {
@@ -57,6 +74,18 @@ export function runDoctor(config) {
         credentialCheck('HUDU_API_KEY', config.HUDU_API_KEY, isStdio),
     ];
     const bases = [baseCheck('HUDU_BASE_URL', config.HUDU_BASE_URL)];
+    // Present only when the deployment configured the pair: a report without the tier keeps exactly
+    // the shape operators already script against.
+    const typesenseBlock = typesenseSearchBlock(config);
+    const typesense = typesenseBlock === undefined
+        ? undefined
+        : {
+            configured: true,
+            // The pair is validated at boot, so a configured block always has a key; the field is
+            // reported anyway because "key present" is the question an operator actually asks.
+            keyPresent: typesenseBlock.apiKey.trim() !== '',
+            urlShapeOk: isTypesenseOrigin(typesenseBlock.url),
+        };
     const notes = [
         'zero vendor requests: this report is computed from the environment alone',
         'shape facts only (length, two-character prefix, anomaly names) — a credential value is never read out',
@@ -67,12 +96,16 @@ export function runDoctor(config) {
     if (credentials.some((c) => c.blocks)) {
         notes.push('a credential-bearing variable would be refused by the server: fix the load recipe before any live session (a 401 costs a real vendor auth failure, and repeated ones risk an account lock)');
     }
+    if (typesense !== undefined) {
+        notes.push('typesense body tier configured: shape only (no request, no key material); hudu_get_api_info reports reachability');
+    }
     return {
         ok: !credentials.some((c) => c.blocks) && bases.every((b) => !b.present || b.resolvable),
         transport: config.MCP_TRANSPORT,
         dialed: 0,
         credentials,
         bases,
+        ...(typesense === undefined ? {} : { typesense }),
         notes,
     };
 }

package/dist/main.js

@@ -7,7 +7,7 @@
  */
 import { createRequire } from 'node:module';
 import { createMcpHandler } from '@modelcontextprotocol/server';
-import { ConfigError, loadConfig } from './config.js';
+import { ConfigError, describeTypesense, loadConfig } from './config.js';
 import { logEffectiveWritePolicy } from './policy.js';
 import { runDoctor } from './doctor.js';
 import { createLogger } from './logger.js';
@@ -87,6 +87,12 @@ function main() {
     }
     const log = createLogger(config.LOG_LEVEL);
     logEffectiveWritePolicy(config, log, process.env);
+    // Shapes only: whether the body tier is on and which collections it searches. The URL and the
+    // key never reach a log sink (DESIGN §4 WP-7). An UNCONFIGURED deployment logs nothing at all —
+    // "typesense: disabled" on every stock boot would contradict the byte-identical promise.
+    const typesenseLine = describeTypesense(config);
+    if (typesenseLine !== undefined)
+        log.info(typesenseLine);
     // `HUDU_SEARCH_TIER_POLICY=index` under `http` re-introduces the #49 blocking wait on purpose:
     // every caller's scope starts cold, so each first call can wait on a corpus-wide body-index walk.
     // Make the trade visible to the operator who set it; never fail the boot over it.