@bongos/core 1.19.269 → 1.19.271

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.269",
-  "core_contract": "1.19.269",
-  "source_commit": "eb9189a55c35d65f7b127a4f825cf15111450f45",
+  "core_version": "1.19.271",
+  "core_contract": "1.19.271",
+  "source_commit": "eeda0eaa782f69e7843920d6ba6027133ffaf889",
   "source_ref": "HEAD",
-  "built_at": "2026-08-20T23:06:25.339Z",
+  "built_at": "2026-08-21T01:46:51.577Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 318,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1368,
+    "functional_verbatim": 1369,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1708,
-  "tree_sha256": "1bb1e8f0972473d957a4d18ab8cb07dc0e7320b9c00e1e504bbd939804fc8b3e",
+  "file_count": 1709,
+  "tree_sha256": "552e1f0cff6b4913becf9550cc1d368053a56c1022f8ed7c6f373f3028ae69fe",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -367,7 +367,7 @@
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "1c790a9dca384a70cba29ba814cff546cdd69eb784f512fb88e06c336b3f75a9"
+      "sha256": "96bbd222f3ccbc2d57bce28e0ac89584252b0e3213bc79f5c8aad54ce10cc845"
     },
     {
       "path": "clients/bongos-client/index.mjs",
@@ -1402,7 +1402,7 @@
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "979d2d19c20a8d4eb4fb7f4715ef307c40d64b99038d0d816702a50bd211fcc9"
+      "sha256": "2f14ac090adc4b7de69f20948172cee0cf002e1224262d5a51ddcada95ad9489"
     },
     {
       "path": "docs/architecture.md",
@@ -3907,7 +3907,7 @@
     {
       "path": "modules/memory/routes/search.js",
       "mode": "0000644",
-      "sha256": "3f3e2d2e1d51f17c436668c27faa72916434c706fa14a7daaffbd363d10030dd"
+      "sha256": "a79f61f7906393fcb0bffb67f224c47b7129223e3a6806357de091a9339fa42e"
     },
     {
       "path": "modules/memory/search-chunker.js",
@@ -3917,7 +3917,7 @@
     {
       "path": "modules/memory/search.js",
       "mode": "0000644",
-      "sha256": "6ca89effa3792d71982c32c2d3d6b69253a8063a32a84a5f78e3fe18b6186b39"
+      "sha256": "a9b900bcbdbb55b27f15dafe3ee45f57cd0e4dfda0b32cb38b29139b24f4ef68"
     },
     {
       "path": "modules/onboarding/CLAUDE.md",
@@ -4472,12 +4472,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "ddb6a432b5c2aab632e59179fa2429ac1055aa0eaac7ea30e94c7cba0e4cf8e8"
+      "sha256": "289d96460bbde068311ad18505bfca432c201de66af827055b8ce2ed31ac81be"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "00d26fc1394b365885ef97c011108dfbe1734aa49ed388a8c49a308480fe3b5a"
+      "sha256": "2ec9e8fb9b470df255d1de4adc52597ca9f6dac5a301adbdecd0cf249547938d"
     },
     {
       "path": "public-docs/index.html",
@@ -5447,7 +5447,7 @@
     {
       "path": "scripts/gds/recall.js",
       "mode": "0000644",
-      "sha256": "564996b820fa09ccb95bcef2e5a1b57f22e5b16c4e54b67dfe1a2cd37ff716a4"
+      "sha256": "191b81d68114cbb920d2aed23398d581d2e1d51f6bc92e243ae7541f454d4b1e"
     },
     {
       "path": "scripts/gds/redteam-patrol.js",
@@ -6122,7 +6122,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "f87f3562ac47d91ae9031fbc80d64b2200e1a7ca2c5bfebab13d0bf0f2197b2a"
+      "sha256": "bc19b591ad45c693adebe95bf3df3e480b174bac7b109df27dd45fb088e78537"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -7984,6 +7984,11 @@
       "mode": "0000644",
       "sha256": "dedec6f449696a7fefa2cec1aeb290dc91386c4450e8feaf28a49e9b46a5e7ed"
     },
+    {
+      "path": "tests/recall_corpus_health.mjs",
+      "mode": "0000644",
+      "sha256": "ec1ebb9e317221df08c6009d1abd8816da47eda20740ae928cf9f829b8da4951"
+    },
     {
       "path": "tests/recall_hints.mjs",
       "mode": "0000644",

package/clients/bongos-client/index.d.ts

@@ -278,7 +278,7 @@ export interface PostProvisioningInstancesIdTeardownResponse { ok: boolean; queu
 export interface PostProvisioningInstancesRequest { slug: string; target_ref?: string; hosting_shape?: string; domain?: string; no_address?: boolean; tier?: string; onboard_mode?: string; type?: string }
 export interface PostSearchMarkRequest { chunk_id?: StringifiableId; useful?: unknown }
 export interface PostSearchRequest { expand?: unknown; q?: string; source_kind?: string; limit?: unknown }
-export interface PostSearchResponse { expand?: unknown; chunk?: unknown; query?: unknown; count?: unknown; total_full_tokens?: unknown; results?: unknown }
+export interface PostSearchResponse { expand?: unknown; chunk?: unknown; query?: unknown; count?: unknown; total_full_tokens?: unknown; results?: unknown; corpus?: unknown }
 export interface PostSecurityDocsRequest { slug: string; title: string; content_md: string }
 export interface PostSecurityDocsResponse { ok: boolean; doc: unknown }
 export interface PostSecurityReportsIdConfirmRequest { drachmae_awarded?: unknown }

package/docs/api/openapi.json

@@ -17187,7 +17187,8 @@
           "query": {},
           "count": {},
           "total_full_tokens": {},
-          "results": {}
+          "results": {},
+          "corpus": {}
         }
       },
       "PostSecurityDocsRequest": {

package/modules/memory/routes/search.js

@@ -128,7 +128,25 @@ module.exports = function buildSearchRouter() {
       // total_full_tokens: the cost of expanding EVERY hit — the headline an
       // agent reads to decide whether to expand selectively (ADR 0095 C1).
       const totalFullTokens = results.reduce((sum, r) => sum + (r.full_tokens || 0), 0);
-      return res.json({ query: q, count: results.length, total_full_tokens: totalFullTokens, results });
+      // task 1003097: a zero-result search is ambiguous on the wire — a DEAD
+      // INDEX and a genuine miss are the same 200-with-an-empty-array, which is
+      // how /recall stayed broken for weeks with nothing reporting a fault. On
+      // the zero path only (so a healthy search pays nothing), ask the corpus why
+      // and say which of the three it was. Best-effort: a diagnostic must never
+      // turn a working search into a 500.
+      // corpusHealth absorbs its own failures (enrichment must never break a
+      // working search), so no try/catch here. `corpus` stays undefined on a
+      // hit, and JSON.stringify drops an undefined key — so a successful search
+      // is byte-identical on the wire, and the response literal stays STATIC so
+      // gen-api-docs can still infer PostSearchResponse from it.
+      let corpus;
+      if (results.length === 0) {
+        const health = await search.corpusHealth({ builderId: req.builder.id, builderRank: req.builder.rank });
+        // ONLY the classifier's output — it returns the SAFE subset. Spreading
+        // `health` here would put the unscoped existence probe back on the wire.
+        corpus = search.classifyEmptyResult(health);
+      }
+      return res.json({ query: q, count: results.length, total_full_tokens: totalFullTokens, results, corpus });
     } catch (err) {
       console.error('[gds] POST /search', { builderId: req.builder.id, err: err && err.message });
       return res.fail('search_failed', { status: 500, message: 'search could not be completed' });

package/modules/memory/search.js

@@ -304,8 +304,178 @@ async function markChunkUsefulness(
   };
 }
 
+// task 1003097: WHY A ZERO-RESULT SEARCH IS NOT SELF-EXPLANATORY.
+//
+// /recall returned zero matches for EVERY query on live for weeks and nothing
+// reported a fault, because a dead index and a genuine no-match are the same
+// 200-with-an-empty-array on the wire. That is the most expensive possible wrong
+// answer: it reads as "we have never touched this", so sessions re-derive work
+// that already exists. (The cause was task 1002859 — one NUL byte rolled back
+// the whole ingest, silently, on every deploy.)
+//
+// So when a search finds nothing, ask the corpus WHY and say which of three
+// things happened. One cheap aggregate, run ONLY on the zero-result path, so a
+// healthy search pays nothing:
+//
+//   index_empty      — there are no chunks at all. The ingest has never
+//                      succeeded, or the table was wiped and never rebuilt.
+//                      This is an OUTAGE, not an answer.
+//   nothing_visible  — chunks exist, but none are visible at this caller's rank
+//                      or ownership. Scoping, not absence — and worth naming,
+//                      because the scope join is the other candidate cause a
+//                      diagnosis has to rule out.
+//   no_match         — the corpus is populated and visible, and the query
+//                      genuinely matched nothing. The only one of the three that
+//                      is a legitimate "no results".
+//
+// NOTE for anyone reading task 1003097's brief: it points at "migration 127
+// search_ingest_runs" as an ingest ledger to consult. No such table exists in
+// this repo (the search schema is migration 103, search_chunks alone), so
+// freshness here is derived from MAX(updated_at) on the chunks themselves.
+// Who may be told about content they cannot read. Metic+ is the boundary this
+// repo already uses for the permission/methodology core (ADR 0043), and
+// distinguishing "the index is empty" from "everything is above your rank"
+// necessarily reveals that unreadable content exists.
+const PRIVILEGED_DIAGNOSTIC_RANKS = ['metic', 'archon'];
+
+// task 1003097: why a zero-result search is not self-explanatory.
+//
+// /recall returned zero for EVERY query on live for weeks and nothing reported a
+// fault, because a dead index and a genuine no-match are the same
+// 200-with-an-empty-array. That reads as "we have never touched this", so
+// sessions re-derive work that already exists. (Cause: task 1002859 — one NUL
+// byte rolled back the whole ingest, silently, every deploy.)
+//
+// Two panel findings shaped this into its current form, and both are worth
+// keeping in view:
+//
+//   SCOPING (ADR 0016). The first cut returned unfiltered total/doc/db counts and
+//   a global last_indexed_at to every caller — an oracle for the size,
+//   composition and freshness of content the caller may not read. This route
+//   family deliberately avoids that (fetchChunkBody answers one 404 for both
+//   "missing" and "not yours"). Now: the caller's own view is scoped with the
+//   SAME predicate as the search, and the unscoped probe is only consulted for a
+//   Metic+ caller.
+//
+//   COST. It also ran a full-table COUNT(*) — and during an actual outage EVERY
+//   search is a zero-result search, so that scan would run on every request from
+//   every builder for the duration. But nothing here needs a COUNT: the states
+//   turn on whether ANY row exists, not how many. EXISTS short-circuits at the
+//   first matching row, so this is two index-assisted probes rather than a scan,
+//   and it stays flat as the corpus grows. Dropping the exact numbers also
+//   removes the last of the oracle.
+async function corpusHealth({ builderId, builderRank } = {}, { pool: p = pool, client = null } = {}) {
+  const allowedRanks = ranksAtOrBelow(builderRank);
+  const ownerId = Number.isInteger(builderId) ? builderId : (Number(builderId) || null);
+  const privileged = PRIVILEGED_DIAGNOSTIC_RANKS.includes(String(builderRank || '').toLowerCase());
+  const sql = `
+    SELECT EXISTS (
+             SELECT 1 FROM search_chunks
+              WHERE min_rank = ANY($1::text[])
+                AND (owner_builder_id IS NULL OR owner_builder_id = $2::bigint)
+           ) AS any_visible,
+           -- Unscoped existence. Consulted ONLY for a privileged caller (the
+           -- route passes it straight to classifyEmptyResult, which strips it
+           -- for everyone else), and cheap either way because EXISTS stops at
+           -- the first row.
+           EXISTS (SELECT 1 FROM search_chunks) AS any_at_all,
+           (SELECT MAX(updated_at) FROM search_chunks
+             WHERE min_rank = ANY($1::text[])
+               AND (owner_builder_id IS NULL OR owner_builder_id = $2::bigint)
+           ) AS last_indexed_at
+  `;
+  const runner = client || p;
+  let rows;
+  try {
+    ({ rows } = await runner.query(sql, [allowedRanks, ownerId]));
+  } catch (_) {
+    // ENRICHMENT ONLY — it runs to EXPLAIN a zero result, so it must never turn
+    // a working search into an error. Nulls fail closed through
+    // classifyEmptyResult, which never reports health it cannot prove.
+    return { any_visible: null, any_at_all: null, last_indexed_at: null, privileged };
+  }
+  const r = rows[0] || {};
+  return {
+    any_visible: r.any_visible === true || r.any_visible === false ? r.any_visible : null,
+    any_at_all: r.any_at_all === true || r.any_at_all === false ? r.any_at_all : null,
+    last_indexed_at: r.last_indexed_at || null,
+    privileged,
+  };
+}
+
+// PURE. The state, the sentence to show, and only the facts this caller may
+// have. Separated from the query so the truth table AND the scoping are
+// unit-tested without a DB.
+function classifyEmptyResult(health) {
+  const anyVisible = health && typeof health.any_visible === 'boolean' ? health.any_visible : null;
+  const privileged = !!(health && health.privileged);
+  // Never echo the unscoped probe. last_indexed_at is already scoped to the
+  // caller's own view by the query.
+  const safe = { last_indexed_at: (health && health.last_indexed_at) || null };
+
+  if (anyVisible === null) {
+    return {
+      ...safe,
+      state: 'unknown',
+      healthy: false,
+      message: 'The index could not be inspected, so this zero cannot be interpreted — it may be an '
+        + 'empty corpus, a scoping wall, or a real miss. Treat it as UNKNOWN rather than as "nothing '
+        + 'exists", and check the server log for the search-corpus probe.',
+    };
+  }
+
+  if (anyVisible) {
+    return {
+      ...safe,
+      state: 'no_match',
+      healthy: true,
+      message: 'No match. The index is populated and visible to you, and the query ran, so this is a '
+        + 'genuine miss — try fewer or different terms.',
+    };
+  }
+
+  // Nothing visible. WHETHER that is an empty corpus or a scoping wall is a fact
+  // about content this caller cannot read, so only Metic+ is told which.
+  if (!privileged) {
+    return {
+      ...safe,
+      state: 'nothing_visible_to_you',
+      healthy: false,
+      message: 'NOTHING IS VISIBLE TO YOU HERE — either the index is empty or everything in it is '
+        + 'scoped above your rank. This answer does not distinguish them, so do NOT read it as "the '
+        + 'project has never touched this subject". Ask a Metic+ to check whether the index needs '
+        + 'rebuilding.',
+    };
+  }
+
+  if (health.any_at_all === false) {
+    return {
+      ...safe,
+      state: 'index_empty',
+      healthy: false,
+      message: 'THE SEARCH INDEX IS EMPTY — this is an outage, not an answer. No chunk has ever been '
+        + 'written, or the table was wiped and never rebuilt. Nothing can be found until an ingest '
+        + 'succeeds: run `node scripts/gds/search-ingest-md.js` (repo docs) and '
+        + '`node scripts/gds/search-ingest-db.js` (DB prose), and check their exit codes — they run '
+        + 'best-effort from the deploy and a failure there is easy to miss (task 1002859).',
+    };
+  }
+  return {
+    ...safe,
+    state: 'nothing_visible',
+    healthy: false,
+    message: 'The index is NOT empty, but nothing in it is visible to you — every chunk is scoped '
+      + 'above your rank or owned by another builder. This is a scoping result, not an empty corpus, '
+      + 'so a zero here says nothing about whether the subject is documented.',
+  };
+}
+
 module.exports = {
   searchChunks,
+  // task 1003097: a zero-result search must say WHICH of three things happened —
+  // a dead index, a scoping wall, or a genuine miss.
+  corpusHealth,
+  classifyEmptyResult,
   fetchChunkBody,
   markChunkUsefulness,
   ranksAtOrBelow,

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.269",
+  "version": "1.19.271",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.269",
+      "version": "1.19.271",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.269",
+  "version": "1.19.271",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/recall.js

@@ -73,6 +73,41 @@ async function runExpand(args) {
   console.log(c.body);
 }
 
+
+// task 1003097: the zero-result message, as a PURE function of (query, corpus)
+// so the three outcomes are unit-tested instead of eyeballed.
+//
+// The old single line hedged — "or it may not be indexed yet" — which reads
+// identically whether the index is fine or completely dead. /recall returned zero
+// for EVERY query for weeks and this sentence was the only thing a builder saw,
+// so it read as "we have never touched this" and sessions re-derived work that
+// already existed. Returns { stream, lines, exitCode }: an OUTAGE goes to stderr
+// with a non-zero exit, because a scheduled routine scripting /recall has to be
+// able to tell a broken index from an honest miss.
+function renderNoMatch({ q, corpus }) {
+  if (!corpus || !corpus.message) {
+    // Older server with no corpus diagnostic — previous wording, unchanged.
+    return {
+      stream: 'out',
+      exitCode: 0,
+      lines: [`No matches for "${q}". The index covers repo docs + (nightly) DB prose; try fewer / different terms, or it may not be indexed yet.`],
+    };
+  }
+  const stamp = corpus.last_indexed_at ? ` Last indexed: ${corpus.last_indexed_at}.` : '';
+  if (corpus.healthy) {
+    return { stream: 'out', exitCode: 0, lines: [`No matches for "${q}". ${corpus.message}${stamp}`] };
+  }
+  return {
+    stream: 'err',
+    exitCode: 1,
+    lines: [
+      `\n  ⚠ RECALL IS NOT ANSWERING — "${q}" returned nothing, and the reason is not your query.\n`,
+      `  ${corpus.message}${stamp}\n`,
+      '  Do NOT read this as "the project has never touched this subject".\n',
+    ],
+  };
+}
+
 async function main() {
   const args = parseArgs(process.argv.slice(2));
 
@@ -102,9 +137,12 @@ async function main() {
     return;
   }
 
-  const { count, results, total_full_tokens } = r.data;
+  const { count, results, total_full_tokens, corpus } = r.data;
   if (!count) {
-    console.log(`No matches for "${args.q}". The index covers repo docs + (nightly) DB prose; try fewer / different terms, or it may not be indexed yet.`);
+    const out = renderNoMatch({ q: args.q, corpus });
+    const sink = out.stream === 'err' ? console.error : console.log;
+    for (const line of out.lines) sink(line);
+    if (out.exitCode) process.exitCode = out.exitCode;
     return;
   }
   const totalNote = Number.isFinite(total_full_tokens)
@@ -132,4 +170,4 @@ if (require.main === module) {
   main().catch((e) => { console.error('recall: error', e && e.message ? e.message : e); process.exit(1); });
 }
 
-module.exports = { parseArgs, truncate };
+module.exports = { parseArgs, truncate, renderNoMatch };

package/src/module-api.js

@@ -965,8 +965,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.267 with no explicit bump. run 32407127474. (task 1002620)
 //   1.19.269 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.268 with no explicit bump. run 32427178123. (task 1002620)
+//   1.19.270 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.269 with no explicit bump. run 32428659648. (task 1002620)
+//   1.19.271 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.270 with no explicit bump. run 32437463473. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.269'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.271'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/recall_corpus_health.mjs

@@ -0,0 +1,194 @@
+// tests/recall_corpus_health.mjs — task 1003097.
+//
+// THE OUTAGE THIS PREVENTS RECURRING: /recall returned zero matches for EVERY
+// query on live for weeks, and nothing anywhere reported a fault, because a DEAD
+// INDEX and a genuine no-match are the same 200-with-an-empty-array on the wire.
+// The CLI's one line even hedged toward the wrong reading — "or it may not be
+// indexed yet" — so a total outage looked like "the project has never touched
+// this subject", which is the most expensive possible wrong answer: sessions then
+// re-derive work that already exists. (Cause: task 1002859.)
+//
+// The fix is that a zero result now says WHICH of three things happened. What we
+// prove here (pure — no DB, no network):
+//   1. The truth table: no chunks at all -> index_empty (an outage);
+//      chunks exist but none visible -> nothing_visible (scoping, and the OTHER
+//      candidate cause a diagnosis must rule out); populated + visible -> the one
+//      legitimate no_match.
+//   2. Only no_match is marked healthy — so nothing downstream can mistake an
+//      outage for an answer.
+//   3. The CLI renders an outage to STDERR with a NON-ZERO EXIT (a scheduled
+//      routine scripting /recall must be able to tell a broken index from an
+//      honest miss), a genuine miss to stdout with exit 0, and stays
+//      backward-compatible with a server that sends no diagnostic at all.
+//   4. The outage text tells the reader what to run, and explicitly contradicts
+//      the wrong inference.
+//
+// Run:  node tests/recall_corpus_health.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const search = require('../modules/memory/search.js');
+const { renderNoMatch } = require('../scripts/gds/recall.js');
+const { classifyEmptyResult } = search;
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.message}`); }
+}
+
+// ---- 1/2. the truth table, and the scoping ----
+
+test('nothing visible + index HAS content: a sub-Metic is not told which', () => {
+  // Panel finding (ADR 0016): distinguishing "empty" from "above your rank" is a
+  // fact ABOUT CONTENT THE CALLER CANNOT READ. This route family already answers
+  // one 404 for both "missing" and "not yours"; the diagnostic must not become
+  // the oracle that surface refuses to be.
+  const c = classifyEmptyResult({ any_visible: false, any_at_all: true, privileged: false });
+  assert.equal(c.state, 'nothing_visible_to_you');
+  assert.equal(c.healthy, false);
+  assert.match(c.message, /does not distinguish them/, 'says plainly that it is not telling');
+  assert.match(c.message, /Ask a Metic\+/, 'and routes the caller to someone who can find out');
+  assert.match(c.message, /do NOT read it as "the project has never touched this subject"/i);
+});
+
+test('the SAFE subset never carries the unscoped probe, at any rank', () => {
+  for (const privileged of [false, true]) {
+    for (const any_at_all of [true, false]) {
+      const c = classifyEmptyResult({ any_visible: false, any_at_all, privileged });
+      assert.ok(!('any_at_all' in c), 'the unscoped existence probe must never reach the caller');
+      assert.ok(!('total_chunks' in c), 'and no global count either');
+      assert.ok(!('privileged' in c), 'nor the rank decision itself');
+    }
+  }
+});
+
+test('a Metic+ IS told which — empty index vs scoping wall', () => {
+  const empty = classifyEmptyResult({ any_visible: false, any_at_all: false, privileged: true });
+  assert.equal(empty.state, 'index_empty');
+  assert.equal(empty.healthy, false);
+  assert.match(empty.message, /outage, not an answer/);
+  assert.match(empty.message, /search-ingest-md\.js/, 'names what to run');
+  assert.match(empty.message, /search-ingest-db\.js/);
+  assert.match(empty.message, /exit codes/, 'and why the failure was missable');
+
+  const walled = classifyEmptyResult({ any_visible: false, any_at_all: true, privileged: true });
+  assert.equal(walled.state, 'nothing_visible');
+  assert.equal(walled.healthy, false);
+  assert.match(walled.message, /scoping result, not an empty corpus/);
+  assert.doesNotMatch(walled.message, /\d+ chunk/, 'no exact count — that was the oracle');
+});
+
+test('anything visible → no_match, the ONLY healthy zero', () => {
+  for (const privileged of [false, true]) {
+    const c = classifyEmptyResult({ any_visible: true, any_at_all: true, privileged });
+    assert.equal(c.state, 'no_match');
+    assert.equal(c.healthy, true);
+    assert.match(c.message, /genuine miss/);
+  }
+});
+
+test('a probe that could not be READ is "unknown", never reported as empty', () => {
+  // corpusHealth absorbs its own errors, so a failed probe yields nulls.
+  // Reporting that as "the index is empty, run the ingest" would be a confident
+  // wrong answer — the exact failure mode this task exists to remove.
+  for (const input of [undefined, null, {}, { any_visible: null, privileged: true }]) {
+    const c = classifyEmptyResult(input);
+    assert.equal(c.state, 'unknown', `handled ${JSON.stringify(input)}`);
+    assert.equal(c.healthy, false, 'never claim health we cannot prove');
+    assert.doesNotMatch(c.message, /search-ingest-md/, 'must NOT prescribe a fix for a cause it has not established');
+  }
+});
+
+// ---- 3/4. what the builder actually sees ----
+
+test('an outage goes to STDERR with a non-zero exit', () => {
+  const corpus = classifyEmptyResult({ any_visible: false, any_at_all: false, privileged: true });
+  const out = renderNoMatch({ q: 'board room ratification', corpus });
+  assert.equal(out.stream, 'err', 'an outage is not normal output');
+  assert.equal(out.exitCode, 1, 'a scripted caller must be able to detect it');
+  const text = out.lines.join('\n');
+  assert.match(text, /RECALL IS NOT ANSWERING/);
+  assert.match(text, /the reason is not your query/);
+  assert.match(text, /Do NOT read this as "the project has never touched this subject"/,
+    'the wrong inference must be contradicted explicitly — it is the whole cost of this bug');
+});
+
+test('a genuine miss stays ordinary stdout with exit 0', () => {
+  const corpus = { ...classifyEmptyResult({ any_visible: true, any_at_all: true, privileged: false }), last_indexed_at: '2026-08-20T00:00:00.000Z' };
+  const out = renderNoMatch({ q: 'nonexistent gibberish', corpus });
+  assert.equal(out.stream, 'out');
+  assert.equal(out.exitCode, 0);
+  const text = out.lines.join('\n');
+  assert.doesNotMatch(text, /RECALL IS NOT ANSWERING/, 'never cry outage on an honest miss');
+  assert.match(text, /Last indexed: 2026-08-20/, 'freshness is still surfaced');
+});
+
+test('a server that sends no diagnostic keeps the previous behaviour', () => {
+  // Backward compatibility matters here in particular: the fix ships before the
+  // pin moves, so a new CLI will talk to an OLD server for a while.
+  const out = renderNoMatch({ q: 'anything', corpus: undefined });
+  assert.equal(out.stream, 'out');
+  assert.equal(out.exitCode, 0);
+  assert.match(out.lines.join('\n'), /No matches for "anything"/);
+});
+
+// ---- wiring ----
+
+test('the route asks for the diagnostic ONLY on the zero-result path', () => {
+  // A healthy search must not pay for an extra aggregate.
+  const src = fs.readFileSync(path.join(ROOT, 'modules/memory/routes/search.js'), 'utf8');
+  const idx = src.indexOf('search.corpusHealth');
+  assert.ok(idx > 0, 'the route consults corpusHealth');
+  const before = src.slice(Math.max(0, idx - 300), idx);
+  assert.match(before, /if \(results\.length === 0\)/, 'gated on the zero path');
+});
+
+test('the response literal stays STATIC so the OpenAPI schema survives', () => {
+  // A conditional spread in res.json() defeated gen-api-docs's literal parser
+  // and silently DELETED the whole PostSearchResponse schema from the spec.
+  // `corpus` is always a key (undefined on a hit — JSON.stringify drops it), so
+  // the wire shape of a successful search is unchanged and the schema holds.
+  const src = fs.readFileSync(path.join(ROOT, 'modules/memory/routes/search.js'), 'utf8');
+  assert.match(src, /res\.json\(\{ query: q, count: results\.length, total_full_tokens: totalFullTokens, results, corpus \}\)/,
+    'the search response must be a flat, static object literal');
+  assert.doesNotMatch(src, /\.\.\.\(corpus \?/, 'no conditional spread in the response literal');
+  const spec = JSON.parse(fs.readFileSync(path.join(ROOT, 'docs/api/openapi.json'), 'utf8'));
+  const schema = spec.components.schemas.PostSearchResponse;
+  assert.ok(schema, 'PostSearchResponse must still exist in the spec');
+  assert.ok('corpus' in schema.properties, 'and now document the corpus diagnostic');
+});
+
+test('corpusHealth probes EXISTENCE, scoped with the same predicate as the search', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'modules/memory/search.js'), 'utf8');
+  const fn = src.slice(src.indexOf('async function corpusHealth'));
+  const body = fn.slice(0, fn.indexOf('\n}'));
+  // EXISTS, not COUNT: during an outage EVERY search is a zero-result search, so
+  // a full-table scan here would run on every request from every builder for the
+  // duration. EXISTS short-circuits at the first row and stays flat as the
+  // corpus grows.
+  assert.doesNotMatch(body, /COUNT\(\*\)/, 'no full-table count on the zero path');
+  assert.match(body, /EXISTS \(/, 'existence probes instead');
+  assert.match(body, /min_rank = ANY/, 'the visible probe is rank-scoped');
+  assert.match(body, /owner_builder_id IS NULL OR owner_builder_id/, 'with the search\'s own ownership predicate');
+  assert.match(body, /MAX\(updated_at\)/, 'freshness, also scoped');
+});
+
+test('the route hands the caller ONLY the classifier output', () => {
+  // Spreading `health` into the response would put the unscoped probe back on
+  // the wire — the regression this ordering exists to prevent.
+  const src = fs.readFileSync(path.join(ROOT, 'modules/memory/routes/search.js'), 'utf8');
+  assert.match(src, /corpus = search\.classifyEmptyResult\(health\);/);
+  assert.doesNotMatch(src, /\.\.\.health/, 'never spread the raw health object into the response');
+});
+
+console.log('');
+console.log(`recall_corpus_health: ${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);