@bongos/core 1.19.268 → 1.19.270

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.268",
-  "core_contract": "1.19.268",
-  "source_commit": "8404da50e0a2a9b46c5e644ea1c8df208dd39dcd",
+  "core_version": "1.19.270",
+  "core_contract": "1.19.270",
+  "source_commit": "b552261cf04dbe95edbfa682bdeb797004935248",
   "source_ref": "HEAD",
-  "built_at": "2026-08-20T19:10:01.449Z",
+  "built_at": "2026-08-20T23:27:09.964Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 318,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1367,
+    "functional_verbatim": 1369,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1707,
-  "tree_sha256": "5f4702b206311a36e72366847e94d28a71690f05d8f0b0151c94d7a508b6a9e2",
+  "file_count": 1709,
+  "tree_sha256": "fd8774b261076703d5db5da8703522555606efc1b3463642d9ded0253791b414",
   "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,17 +3907,17 @@
     {
       "path": "modules/memory/routes/search.js",
       "mode": "0000644",
-      "sha256": "3f3e2d2e1d51f17c436668c27faa72916434c706fa14a7daaffbd363d10030dd"
+      "sha256": "a79f61f7906393fcb0bffb67f224c47b7129223e3a6806357de091a9339fa42e"
     },
     {
       "path": "modules/memory/search-chunker.js",
       "mode": "0000644",
-      "sha256": "5eaebeb1d9a8c134a7e5f7ab532486dcf608181ee212ab46bb5f9bcee9951637"
+      "sha256": "b25ec0c42b9ea0ac856837e9a4282fd9ea4cb79a1c9258ee18bdf81e757c001e"
     },
     {
       "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": "219416dda396230765f92ee473d65aa00d9e8c28308e7a4cce723455da79927b"
+      "sha256": "3da63688ee1642c534fe9f8c177822c8de4335ed57c30878366e4a59f6a94a31"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "22c9c3c9513d9e53575718a26daba800488dd9ab3f5b7521c83edf515b1f2b89"
+      "sha256": "1b3cda6b70ab6ff9c4034e5a459a3ea8b6bdeb39ad6368e0627d0a35015ad8c2"
     },
     {
       "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",
@@ -5497,12 +5497,12 @@
     {
       "path": "scripts/gds/search-ingest-db.js",
       "mode": "0000644",
-      "sha256": "c410dfff1628a48ab68b687306335cf2fe73513c04888e73cbb80ba4beb3951b"
+      "sha256": "0723d48df92d78696b86adf0591584800f77da590afc80bcc5e3f99dcf614979"
     },
     {
       "path": "scripts/gds/search-ingest-md.js",
       "mode": "0000644",
-      "sha256": "19b4e880f0a44dcba9458d863ba10686fe67b90f3aed5b595f7b7db4e205e68a"
+      "sha256": "802d16a48f6a47bf41b1768fff3da0ae1b18a4d73147b3559a781f18ea47c75c"
     },
     {
       "path": "scripts/gds/security-baseline-check.sh",
@@ -6122,7 +6122,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "469fc55669b154bc1579b3b451f1dbd6f85851cdca493edbae8c943c0e67c1aa"
+      "sha256": "a70173a565935a8a93c133dd94bde27e0000836e6ec9b043499ab0d27b4f29c2"
     },
     {
       "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",
@@ -8099,6 +8104,11 @@
       "mode": "0000644",
       "sha256": "c80af8bfbb83f0ebdc44c196b8d127caf228a5e102382f254f4e55e1c1d96eaf"
     },
+    {
+      "path": "tests/search_ingest_nul.mjs",
+      "mode": "0000644",
+      "sha256": "a8687493e50f83430b337df76c77e2ecb9924df5012180ba1c853141e0646f88"
+    },
     {
       "path": "tests/search_isolation.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-chunker.js

@@ -168,11 +168,37 @@ function splitLongBody(body, maxTokens) {
 // a typed ref like 'task:431' for DB prose); it's only used for the breadcrumb
 // root + returned for the caller's source_ref. Returns chunks in document order
 // with 0-based chunk_index.
+// task 1002859: strip characters Postgres rejects in a text column. U+0000 is the
+// one that matters: PG raises 'invalid byte sequence for encoding "UTF8": 0x00'
+// on it, and BOTH ingesters (search-ingest-md.js for the tree, search-ingest-db.js
+// for DB prose) hand chunk bodies straight to an INSERT. A NUL therefore aborted
+// the whole ingest and /recall silently stopped re-indexing (task 1003097).
+//
+// Sanitizing HERE rather than in either ingester is deliberate: this is the one
+// funnel both go through, so the guard cannot be added to one path and forgotten
+// on the other. That is exactly what happened the first time this bug class was
+// fixed — commit 75742cb (task 1002507) stripped NUL from ship.js snippetOf after
+// a UTF-16LE `wsl --list` read voided a session digest, and left every other path
+// carrying the same hazard.
+//
+// NUL is meaningless in prose, so dropping it loses nothing a reader wants. Lone
+// surrogates go too: they are unpaired UTF-16 halves that cannot be encoded as
+// valid UTF-8 — the same class of failure from the same class of cause (a file
+// read in the wrong encoding).
+const PG_INVALID_TEXT_RE = /\u0000|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+
+function sanitizeForText(text) {
+  return typeof text === 'string' ? text.replace(PG_INVALID_TEXT_RE, '') : text;
+}
+
 function chunkMarkdown({ path, content, maxTokens = DEFAULT_MAX_TOKENS, targetTokens = DEFAULT_TARGET_TOKENS } = {}) {
   // ADR 0095 C4: strip <private>-fenced content BEFORE chunking so it never
   // enters the recall index. Done first so front-matter parsing + heading
   // splitting see only the public text.
-  const { frontmatter, body } = parseFrontMatter(stripPrivate(content));
+  // Sanitize FIRST, before any parsing: a NUL inside a heading or a front-matter
+  // value would otherwise ride out on `title`/`heading_path`, which are also
+  // Postgres text columns.
+  const { frontmatter, body } = parseFrontMatter(stripPrivate(sanitizeForText(content)));
   const root = fileLabel(path);
 
   // Title: explicit front-matter title/name → first H1 → file label.
@@ -249,4 +275,4 @@ function chunkMarkdown({ path, content, maxTokens = DEFAULT_MAX_TOKENS, targetTo
   return { path: path || null, title, frontmatter: frontmatter || null, chunks };
 }
 
-module.exports = { chunkMarkdown, parseFrontMatter, estTokens, fileLabel, stripPrivate, DEFAULT_TARGET_TOKENS, DEFAULT_MAX_TOKENS };
+module.exports = { chunkMarkdown, parseFrontMatter, estTokens, fileLabel, stripPrivate, sanitizeForText, PG_INVALID_TEXT_RE, DEFAULT_TARGET_TOKENS, DEFAULT_MAX_TOKENS };

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.268",
+  "version": "1.19.270",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.268",
+      "version": "1.19.270",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.268",
+  "version": "1.19.270",
   "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/scripts/gds/search-ingest-db.js

@@ -143,11 +143,26 @@ async function ingestRows(client, rows, sourceRef) {
   return stats;
 }
 
+// task 1002859 (panel finding): bound the driver's error text before it reaches a
+// log. A Postgres error message is unbounded upstream text and CAN embed row
+// content (a constraint violation quotes the offending key), and these logs are
+// deploy/cron sinks that get shipped around. One line, capped, is enough to
+// identify the fault; the source_ref beside it is what actually locates it. The
+// DB corpus makes this matter more than it looks — its prose is session-log and
+// memory-derived text the file elsewhere treats as scrub-sensitive.
+const ERR_LOG_MAX = 300;
+function errLine(e) {
+  const raw = e && e.message ? String(e.message) : String(e);
+  const flat = raw.replace(/\s+/g, ' ').trim();
+  return flat.length > ERR_LOG_MAX ? `${flat.slice(0, ERR_LOG_MAX)}… (truncated)` : flat;
+}
+
 async function main() {
   const dryRun = process.argv.includes('--dry-run');
   const pool = requirePool();
   const client = await pool.connect();
   const totals = { inserted: 0, updated: 0, unchanged: 0, pruned: 0, deleted: 0, sources: 0 };
+  const failures = []; // task 1002859 — per-source casualties, named at the end
   const presentRefs = [];
   try {
     // Gather every source's rows first (read-only), grouped by source_ref.
@@ -177,19 +192,39 @@ async function main() {
       return;
     }
 
-    await client.query('BEGIN');
+    // task 1002859: ONE TRANSACTION PER SOURCE, not one for the whole run — the
+    // same all-or-nothing shape that made a single bad byte a total recall
+    // outage on the markdown side. DB prose is the MORE exposed of the two: it
+    // carries session-log and transcript-derived text, which is exactly where a
+    // wrong-encoding read introduces a NUL in the first place.
     for (const [ref, rows] of byRef) {
-      const s = await ingestRows(client, rows, ref);
-      totals.inserted += s.inserted; totals.updated += s.updated;
-      totals.unchanged += s.unchanged; totals.pruned += s.pruned;
+      try {
+        await client.query('BEGIN');
+        const s = await ingestRows(client, rows, ref);
+        await client.query('COMMIT');
+        totals.inserted += s.inserted; totals.updated += s.updated;
+        totals.unchanged += s.unchanged; totals.pruned += s.pruned;
+      } catch (e) {
+        await client.query('ROLLBACK').catch(() => {});
+        failures.push({ sourceRef: ref, message: errLine(e) });
+        console.error(`search-ingest-db: SKIPPED ${ref} — ${errLine(e)}`);
+      }
     }
     // Delete db chunks whose source no longer exists (a deleted task/idea/etc.).
-    const del = await client.query(
-      `DELETE FROM search_chunks WHERE source_kind='db' AND NOT (source_ref = ANY($1::text[]))`,
-      [presentRefs]
-    );
-    totals.deleted = del.rowCount || 0;
-    await client.query('COMMIT');
+    // Own transaction, and SKIPPED after any failure: presentRefs is what we
+    // meant to write, so pruning against it on a partial run could delete a
+    // still-live source's chunks.
+    if (failures.length === 0) {
+      await client.query('BEGIN');
+      const del = await client.query(
+        `DELETE FROM search_chunks WHERE source_kind='db' AND NOT (source_ref = ANY($1::text[]))`,
+        [presentRefs]
+      );
+      totals.deleted = del.rowCount || 0;
+      await client.query('COMMIT');
+    } else {
+      console.error(`search-ingest-db: vanished-source prune SKIPPED — ${failures.length} source(s) failed, so presentRefs is incomplete`);
+    }
   } catch (e) {
     await client.query('ROLLBACK').catch(() => {});
     console.error('search-ingest-db: FAILED, rolled back:', e.message);
@@ -200,6 +235,13 @@ async function main() {
   client.release();
   await pool.end().catch(() => {});
   console.log(`search-ingest-db: inserted=${totals.inserted} updated=${totals.updated} unchanged=${totals.unchanged} pruned=${totals.pruned} deleted=${totals.deleted} across ${totals.sources} sources`);
+  if (failures.length > 0) {
+    // NON-SILENT: this runs best-effort from a scheduled job, so a non-zero exit
+    // is the only signal that reaches a log a human reads. Name every casualty.
+    console.error(`search-ingest-db: ${failures.length} source(s) FAILED and were skipped:`);
+    for (const f of failures) console.error(`  ${f.sourceRef}: ${f.message}`);
+    process.exitCode = 1;
+  }
 }
 
 if (require.main === module) {

package/scripts/gds/search-ingest-md.js

@@ -163,6 +163,20 @@ async function ingestFile(client, rows, sourceRef) {
   return stats;
 }
 
+// task 1002859 (panel finding): bound the driver's error text before it reaches a
+// log. A Postgres error message is unbounded upstream text and CAN embed row
+// content (a constraint violation quotes the offending key), and these logs are
+// deploy/cron sinks that get shipped around. One line, capped, is enough to
+// identify the fault; the source_ref beside it is what actually locates it. The
+// DB corpus makes this matter more than it looks — its prose is session-log and
+// memory-derived text the file elsewhere treats as scrub-sensitive.
+const ERR_LOG_MAX = 300;
+function errLine(e) {
+  const raw = e && e.message ? String(e.message) : String(e);
+  const flat = raw.replace(/\s+/g, ' ').trim();
+  return flat.length > ERR_LOG_MAX ? `${flat.slice(0, ERR_LOG_MAX)}… (truncated)` : flat;
+}
+
 async function main() {
   const args = process.argv.slice(2);
   const dryRun = args.includes('--dry-run');
@@ -191,32 +205,61 @@ async function main() {
   const pool = requirePool();
   const client = await pool.connect();
   const totals = { inserted: 0, updated: 0, unchanged: 0, pruned: 0, deleted: 0 };
-  try {
-    await client.query('BEGIN');
-    for (const f of allRows) {
+  // task 1002859: ONE TRANSACTION PER FILE, not one for the whole run. The old
+  // shape opened a single BEGIN before this loop, so ANY failure on ANY file
+  // rolled back the ENTIRE index update — that is the "rolls back the entire
+  // re-index" in this task's title, and it is what turned a one-character data
+  // problem into a total, permanent recall outage. Per-file scope makes the
+  // blast radius one file: the other ~900 still land, and the failure is
+  // reported by name instead of vanishing.
+  const failures = [];
+  for (const f of allRows) {
+    try {
+      await client.query('BEGIN');
       const s = await ingestFile(client, f.rows, f.sourceRef);
+      await client.query('COMMIT');
       totals.inserted += s.inserted; totals.updated += s.updated;
       totals.unchanged += s.unchanged; totals.pruned += s.pruned;
+    } catch (e) {
+      await client.query('ROLLBACK').catch(() => {});
+      failures.push({ sourceRef: f.sourceRef, message: errLine(e) });
+      console.error(`search-ingest-md: SKIPPED ${f.sourceRef} — ${errLine(e)}`);
+    }
+  }
+  // Delete chunks for doc sources that no longer exist in the tree. Its own
+  // transaction, and deliberately SKIPPED when any file failed: `present` is the
+  // list of sources we intended to write, so pruning against it after a partial
+  // run could delete chunks for a file that only failed transiently.
+  try {
+    if (failures.length === 0) {
+      await client.query('BEGIN');
+      const present = allRows.map((f) => f.sourceRef);
+      const del = await client.query(
+        `DELETE FROM search_chunks WHERE source_kind='doc' AND NOT (source_ref = ANY($1::text[]))`,
+        [present]
+      );
+      totals.deleted = del.rowCount || 0;
+      await client.query('COMMIT');
+    } else {
+      console.error(`search-ingest-md: vanished-source prune SKIPPED — ${failures.length} file(s) failed, so the present-sources list is incomplete`);
     }
-    // Delete chunks for doc sources that no longer exist in the tree.
-    const present = allRows.map((f) => f.sourceRef);
-    const del = await client.query(
-      `DELETE FROM search_chunks WHERE source_kind='doc' AND NOT (source_ref = ANY($1::text[]))`,
-      [present]
-    );
-    totals.deleted = del.rowCount || 0;
-    await client.query('COMMIT');
   } catch (e) {
     await client.query('ROLLBACK').catch(() => {});
-    console.error('search-ingest-md: FAILED, rolled back:', e.message);
-    process.exitCode = 1;
-    client.release();
-    await pool.end().catch(() => {});
-    return;
+    failures.push({ sourceRef: '(vanished-source prune)', message: errLine(e) });
+    console.error('search-ingest-md: vanished-source prune FAILED:', errLine(e));
   }
   client.release();
   await pool.end().catch(() => {});
   console.log(`search-ingest-md: inserted=${totals.inserted} updated=${totals.updated} unchanged=${totals.unchanged} pruned=${totals.pruned} deleted_sources_chunks=${totals.deleted}`);
+  if (failures.length > 0) {
+    // NON-SILENT (task 1003097's sibling half): the deploy step runs this
+    // best-effort, so a non-zero exit is the only signal that reaches a log a
+    // human reads. Name every casualty — "some files were skipped" is what let
+    // this hide.
+    console.error(`search-ingest-md: ${failures.length} file(s) FAILED and were skipped:`);
+    for (const f of failures) console.error(`  ${f.sourceRef}: ${f.message}`);
+    process.exitCode = 1;
+  }
 }
 
 if (require.main === module) {

package/src/module-api.js

@@ -963,8 +963,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.266 with no explicit bump. run 32404853216. (task 1002620)
 //   1.19.268 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         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)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.268'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.270'; // 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);

package/tests/search_ingest_nul.mjs

@@ -0,0 +1,193 @@
+// tests/search_ingest_nul.mjs — task 1002859.
+//
+// THE OUTAGE: /recall returned zero matches for EVERY query on live (task
+// 1003097), because the doc index was never written. Postgres rejects U+0000 in
+// a text column ('invalid byte sequence for encoding "UTF8": 0x00'), both
+// ingesters handed chunk bodies straight to an INSERT, and both wrapped the
+// WHOLE run in ONE transaction. So one NUL byte in one chunk of one file rolled
+// back the entire index update — and the deploy's search-index step logs
+// non-fatally, so nothing surfaced. A corpus that starts empty (a restore leaves
+// the table empty and expects the ingest to rebuild it) then stays empty
+// forever, and the route answers a legitimate-looking 200 with no results.
+//
+// Same bug class had already been fixed once on a different path: commit 75742cb
+// (task 1002507) stripped NUL from ship.js snippetOf after a UTF-16LE `wsl
+// --list` read voided a session digest — and left every other path exposed.
+//
+// What we prove here (pure — no DB):
+//   1. The sanitizer strips U+0000, and strips lone surrogates too (the same
+//      wrong-encoding cause, also unencodable as UTF-8).
+//   2. It runs at the SHARED funnel (search-chunker), so BOTH ingesters are
+//      covered and the guard cannot be added to one path and forgotten on the
+//      other — which is exactly how this survived the first fix.
+//   3. Nothing a reader wants is lost: sanitizing is a no-op on clean prose.
+//   4. A NUL in a HEADING or a front-matter title is stripped too — title and
+//      heading_path are Postgres text columns as well, so sanitizing only the
+//      body would have left two live vectors.
+//   5. Both ingesters now scope a transaction PER SOURCE, and report failures by
+//      name with a non-zero exit — the blast radius of a bad byte is one file,
+//      not the whole corpus, and it is no longer silent.
+//
+// Run:  node tests/search_ingest_nul.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 chunker = require('../modules/memory/search-chunker.js');
+const { chunkMarkdown, sanitizeForText } = chunker;
+
+// Never write a literal control character into a source file — build it.
+const NUL = String.fromCharCode(0);
+
+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. the sanitizer ----
+
+test('sanitizeForText strips U+0000', () => {
+  assert.equal(sanitizeForText(`a${NUL}b`), 'ab');
+  assert.equal(sanitizeForText(`${NUL}${NUL}lead`), 'lead');
+  assert.equal(sanitizeForText(`trail${NUL}`), 'trail');
+});
+
+test('sanitizeForText strips LONE surrogates but keeps valid pairs', () => {
+  // Unpaired halves cannot be encoded as UTF-8 — same cause (a wrong-encoding
+  // read), same Postgres rejection.
+  assert.equal(sanitizeForText('a\uD800b'), 'ab', 'lone high surrogate');
+  assert.equal(sanitizeForText('a\uDC00b'), 'ab', 'lone low surrogate');
+  // A real astral character is a VALID pair and must survive untouched.
+  assert.equal(sanitizeForText('emoji \u{1F600} ok'), 'emoji \u{1F600} ok');
+});
+
+test('sanitizeForText is a no-op on clean prose and non-strings', () => {
+  const clean = '# Title\n\nSome prose with `code`, an emoji \u{1F680}, and accents: éàü.\n';
+  assert.equal(sanitizeForText(clean), clean);
+  assert.equal(sanitizeForText(null), null);
+  assert.equal(sanitizeForText(undefined), undefined);
+  assert.equal(sanitizeForText(42), 42);
+});
+
+// ---- 2/4. it runs at the shared funnel, and covers title + heading too ----
+
+test('chunkMarkdown strips NUL from body, title AND heading_path', () => {
+  const content = `# Ti${NUL}tle\n\n## Sec${NUL}tion\n\nbo${NUL}dy prose here, long enough to be a chunk.\n`;
+  const { title, chunks } = chunkMarkdown({ path: 'docs/x.md', content });
+  assert.ok(chunks.length > 0, 'produced at least one chunk');
+  assert.equal(title.includes(NUL), false, `title still carries NUL: ${JSON.stringify(title)}`);
+  for (const c of chunks) {
+    assert.equal(c.body.includes(NUL), false, 'body still carries NUL');
+    assert.equal(String(c.heading_path || '').includes(NUL), false, 'heading_path still carries NUL');
+  }
+});
+
+test('a front-matter title carrying NUL is sanitized', () => {
+  const content = `---\ntitle: Fr${NUL}ont\n---\n\nsome body prose here for a chunk.\n`;
+  const { title } = chunkMarkdown({ path: 'docs/y.md', content });
+  assert.equal(title.includes(NUL), false);
+  assert.equal(title, 'Front');
+});
+
+test('the guard lives at the SHARED funnel, so both ingesters inherit it', () => {
+  // The first fix of this bug class (task 1002507) was local to ship.js and left
+  // every other path exposed. Assert structurally that neither ingester relies
+  // on its own private guard: both must reach the sanitizer through chunkMarkdown.
+  for (const rel of ['scripts/gds/search-ingest-md.js', 'scripts/gds/search-ingest-db.js']) {
+    const src = fs.readFileSync(path.join(ROOT, rel), 'utf8');
+    assert.match(src, /chunkMarkdown\(/, `${rel} must chunk through the shared funnel`);
+  }
+  const chunkerSrc = fs.readFileSync(path.join(ROOT, 'modules/memory/search-chunker.js'), 'utf8');
+  assert.match(chunkerSrc, /sanitizeForText\(content\)/, 'the funnel must sanitize its INPUT, before any parsing');
+});
+
+test('chunkFile (the md ingester\'s row builder) emits NUL-free rows', () => {
+  const ingest = require('../scripts/gds/search-ingest-md.js');
+  const tmp = fs.mkdtempSync(path.join(ROOT, '.tmp-nul-'));
+  try {
+    const f = path.join(tmp, 'poisoned.md');
+    fs.writeFileSync(f, `# He${NUL}ad\n\nbo${NUL}dy text long enough to survive chunking.\n`);
+    const rows = ingest.chunkFile(f);
+    assert.ok(rows.length > 0);
+    for (const r of rows) {
+      assert.equal(r.body.includes(NUL), false, 'row body must be clean before the INSERT');
+      assert.equal(String(r.title || '').includes(NUL), false);
+      assert.equal(String(r.heading_path || '').includes(NUL), false);
+      assert.match(r.content_hash, /^[0-9a-f]{64}$/, 'hash is of the SANITIZED body');
+    }
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+// ---- 5. blast radius + non-silence ----
+
+test('both ingesters scope a transaction PER SOURCE, not one per run', () => {
+  // This is the "rolls back the entire re-index" half of the bug. A single BEGIN
+  // before the loop is what turned one bad byte into a total outage.
+  for (const rel of ['scripts/gds/search-ingest-md.js', 'scripts/gds/search-ingest-db.js']) {
+    const src = fs.readFileSync(path.join(ROOT, rel), 'utf8');
+    // Anchor on the loop that actually WRITES (the one calling ingestFile /
+    // ingestRows), not the first `for (const f of ...)` in the file — the
+    // dry-run sample listing uses that shape too.
+    const writeIdx = src.search(/await ingest(File|Rows)\(client/); // the CALL, not the definition
+    assert.ok(writeIdx > 0, `${rel}: found the write call`);
+    const loopIdx = src.lastIndexOf('for (', writeIdx);
+    assert.ok(loopIdx > 0 && writeIdx - loopIdx < 400, `${rel}: the write is inside a loop`);
+    const loopBody = src.slice(loopIdx, writeIdx + 700);
+    assert.match(loopBody, /BEGIN/, `${rel}: BEGIN must be INSIDE the per-source loop`);
+    assert.match(loopBody, /COMMIT/, `${rel}: COMMIT must be inside the loop too`);
+    assert.match(loopBody, /ROLLBACK/, `${rel}: a failing source rolls back only itself`);
+  }
+});
+
+test('a skipped source is named and forces a non-zero exit', () => {
+  // The deploy/cron step runs these best-effort, so the exit code is the only
+  // signal that reaches a log a human reads. "Some files were skipped" is what
+  // let this hide for weeks — every casualty must be named.
+  for (const rel of ['scripts/gds/search-ingest-md.js', 'scripts/gds/search-ingest-db.js']) {
+    const src = fs.readFileSync(path.join(ROOT, rel), 'utf8');
+    assert.match(src, /failures\.push\(/, `${rel}: collects casualties`);
+    assert.match(src, /FAILED and were skipped/, `${rel}: reports them as a group`);
+    assert.match(src, /for \(const f of failures\) console\.error/, `${rel}: names each one`);
+    assert.match(src, /process\.exitCode = 1/, `${rel}: exits non-zero so the deploy log shows it`);
+  }
+});
+
+test('the vanished-source prune is SKIPPED after any failure', () => {
+  // present/presentRefs is the list we MEANT to write. Pruning against it on a
+  // partial run would delete chunks for a source that only failed transiently —
+  // turning a recoverable skip into data loss.
+  for (const rel of ['scripts/gds/search-ingest-md.js', 'scripts/gds/search-ingest-db.js']) {
+    const src = fs.readFileSync(path.join(ROOT, rel), 'utf8');
+    assert.match(src, /failures\.length === 0/, `${rel}: prune is gated on a clean run`);
+    assert.match(src, /prune SKIPPED/, `${rel}: and says so when it skips`);
+  }
+});
+
+test('the driver error text reaching a log is bounded and single-line', () => {
+  // Panel finding: a Postgres error message is unbounded upstream text and CAN
+  // embed row content (a constraint violation quotes the offending key), and
+  // these are deploy/cron log sinks. The DB corpus makes it matter more — its
+  // prose is session-log/memory-derived text the file treats as scrub-sensitive.
+  for (const rel of ['scripts/gds/search-ingest-md.js', 'scripts/gds/search-ingest-db.js']) {
+    const src = fs.readFileSync(path.join(ROOT, rel), 'utf8');
+    assert.match(src, /const ERR_LOG_MAX = \d+;/, `${rel}: declares a cap`);
+    assert.match(src, /function errLine\(e\)/, `${rel}: has the single formatter`);
+    assert.match(src, /truncated/, `${rel}: says when it truncated`);
+    // And nothing may still interpolate the raw driver message directly.
+    assert.doesNotMatch(src, /e && e\.message \? e\.message : (e|String\(e\))/,
+      `${rel}: every error path must go through errLine`);
+  }
+});
+
+console.log('');
+console.log(`search_ingest_nul: ${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);