@bongos/core 1.19.362 → 1.19.363

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.362",
-  "core_contract": "1.19.362",
-  "source_commit": "b42159074c029727d0275823a1726cc7cdfcb3a2",
+  "core_version": "1.19.363",
+  "core_contract": "1.19.363",
+  "source_commit": "dfe3198cbb7ad4104276759b209d6064e4075753",
   "source_ref": "HEAD",
-  "built_at": "2026-08-25T18:50:51.000Z",
+  "built_at": "2026-08-25T19:24:12.550Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 330,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1525,
+    "functional_verbatim": 1527,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1877,
-  "tree_sha256": "04f93b354b8a3bf82452a3cbd157be2d4627d0a3a787a06cb4f2b43da5f46681",
+  "file_count": 1879,
+  "tree_sha256": "11a13769c884c5b71eefc6c2d9d62e17d1096f782583e2b0cdd46ae4a92cf52d",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -2499,6 +2499,11 @@
       "mode": "0000644",
       "sha256": "a379e9f926274559d8c57c9127024463e38b99e3f73962022b9f5d0f4e156a57"
     },
+    {
+      "path": "migrations/core_225_search_chunks_updated_at_idx.sql",
+      "mode": "0000644",
+      "sha256": "1913405bdb9de48ac3ca7ad6705cf44244d20c77d3a6f73700f88e717fb84043"
+    },
     {
       "path": "modules/agents/migrations/agents_001_definitions.sql",
       "mode": "0000644",
@@ -4287,7 +4292,7 @@
     {
       "path": "modules/memory/search.js",
       "mode": "0000644",
-      "sha256": "a9b900bcbdbb55b27f15dafe3ee45f57cd0e4dfda0b32cb38b29139b24f4ef68"
+      "sha256": "43ede2e90d0124c42f6f9dfc3695898b83c8e876c01f70b0ae6e9d2f61d41085"
     },
     {
       "path": "modules/onboarding/CLAUDE.md",
@@ -4847,12 +4852,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "6710729cad476af44279d8772d6e901a5d41133ad9da6f4d5879dbb4db66371f"
+      "sha256": "44644726a2b97729a15e7220d9bc5aa7b7a394580ae95da58b452e8824688ff6"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "9a2f2882dbd2fd617d1c1297a8aa0b0f68d8db2c9fcbf3fa49dafe57e9690022"
+      "sha256": "2dc2136427cf6df206810b410527d3cc09cb3ac72c663f49d0c0ad3bb8a3951c"
     },
     {
       "path": "public-docs/index.html",
@@ -5912,7 +5917,7 @@
     {
       "path": "scripts/gds/recall.js",
       "mode": "0000644",
-      "sha256": "191b81d68114cbb920d2aed23398d581d2e1d51f6bc92e243ae7541f454d4b1e"
+      "sha256": "8bb682eebeec8738082a2988f59697da6982d7c727e82352c169abc72a623b78"
     },
     {
       "path": "scripts/gds/redteam-patrol.js",
@@ -5962,7 +5967,7 @@
     {
       "path": "scripts/gds/run-unit-tests.js",
       "mode": "0000644",
-      "sha256": "b3d816af249491e6187676ad084a60aaa72881615f8824a0263c31505d57a149"
+      "sha256": "21726e53ad33bef62c5a2a0e0d59c380927e06cfa00994d5bbfd9669b83ce167"
     },
     {
       "path": "scripts/gds/sandbox-stage.js",
@@ -6717,7 +6722,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "bb36f1b2c93e5f051a9db15579ac309703db82bbc0b7efaee82416bfb603b487"
+      "sha256": "df48c1828cda7dc37f655dcb890871fd2fd5867f223823eff07a8ae74dd1febe"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -8762,7 +8767,12 @@
     {
       "path": "tests/recall_corpus_health.mjs",
       "mode": "0000644",
-      "sha256": "ec1ebb9e317221df08c6009d1abd8816da47eda20740ae928cf9f829b8da4951"
+      "sha256": "3b379d1fe9c938dac2ad596c5a74022c5476164a57541481f427f22ab17af35e"
+    },
+    {
+      "path": "tests/recall_freshness_plan_db.mjs",
+      "mode": "0000644",
+      "sha256": "94fd5052df816ffad4eaeaff3ec1dfe580a66e7b588756f3b9ca84b68e01081d"
     },
     {
       "path": "tests/recall_hints.mjs",

package/migrations/core_225_search_chunks_updated_at_idx.sql

@@ -0,0 +1,24 @@
+-- core_225_search_chunks_updated_at_idx.sql — task 1003145 (panel finding on 1003097).
+--
+-- corpusHealth() runs a freshness probe on every zero-result search: the newest
+-- updated_at among the chunks VISIBLE to the caller. Migration 103 indexed tsv,
+-- body trigrams, (source_kind, source_ref) and the owner partial — nothing on
+-- updated_at — so that probe was an aggregate over the whole visible corpus. For a
+-- Metic+ caller the scope predicate matches nearly every row, and during an ingest
+-- outage EVERY search is a zero-result search, so it ran on every request from
+-- every builder for the duration. That is the same cost shape that got the
+-- COUNT(*) removed from this path in the first place; the third subquery kept it.
+--
+-- LEADING COLUMN IS updated_at, NOT THE SCOPE COLUMNS. The obvious index here
+-- looks like (min_rank, owner_builder_id, updated_at), but it cannot serve this
+-- query: the scope predicate is `min_rank = ANY($1)` plus an OR on
+-- owner_builder_id, and neither shape lets a btree deliver rows ordered by a
+-- TRAILING column. Ordering on updated_at instead lets the probe walk the index
+-- newest-first and stop at the first row that passes the scope filter — which, for
+-- the privileged caller that was the worst case, is the first row it reads. The
+-- filter costs a heap fetch per candidate, so the win is bounded by how quickly a
+-- visible row turns up, not by the corpus size. search.js asks for that plan
+-- explicitly (ORDER BY updated_at DESC LIMIT 1) rather than leaving it to the
+-- planner's MIN/MAX transform.
+CREATE INDEX IF NOT EXISTS idx_search_chunks_updated_at
+  ON search_chunks (updated_at DESC);

package/modules/memory/search.js

@@ -331,7 +331,8 @@ async function markChunkUsefulness(
 // 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.
+// freshness here is derived from updated_at on the chunks themselves — which is
+// why it reports the last CONTENT CHANGE and not the last ingest run (1003145).
 // 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"
@@ -350,7 +351,7 @@ const PRIVILEGED_DIAGNOSTIC_RANKS = ['metic', 'archon'];
 // 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,
+//   a global freshness stamp 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
@@ -360,10 +361,23 @@ const PRIVILEGED_DIAGNOSTIC_RANKS = ['metic', 'archon'];
 //   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
+//   turn on whether ANY row exists, not how many. Dropping the exact numbers also
 //   removes the last of the oracle.
+//
+// WHAT THIS QUERY COSTS (task 1003145). The comment here used to say "two
+// index-assisted probes rather than a scan", counting only the EXISTS pair and
+// forgetting the third subquery — which was a filtered MAX(updated_at), an
+// AGGREGATE over the whole visible corpus, on a column migration 103 never
+// indexed. Wrong, and load-bearing wrong: a future reader sizing this path would
+// have trusted it. What runs now, all three bounded in the common case:
+//   * the two EXISTS probes stop at the first matching row;
+//   * the freshness probe is ORDER BY updated_at DESC LIMIT 1 over
+//     idx_search_chunks_updated_at (migration 225), so it walks the index
+//     newest-first and stops at the first row that passes the scope filter.
+// The honest remaining worst case is a caller who can see NOTHING: no row passes
+// the filter, so the visible-probe and the freshness probe each read to the end
+// before they can answer. That is the `nothing_visible` state — one of the
+// outages these three states exist to NAME, not a steady-state cost.
 async function corpusHealth({ builderId, builderRank } = {}, { pool: p = pool, client = null } = {}) {
   const allowedRanks = ranksAtOrBelow(builderRank);
   const ownerId = Number.isInteger(builderId) ? builderId : (Number(builderId) || null);
@@ -379,10 +393,27 @@ async function corpusHealth({ builderId, builderRank } = {}, { pool: p = pool, c
            -- 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
+           -- FRESHNESS — and NOT "when the ingest last ran". Both ingesters
+           -- delta-gate their upsert (updated_at = now() fires only when a
+           -- chunk's content actually CHANGED — search-ingest-md.js,
+           -- search-ingest-db.js), so this is the newest CONTENT CHANGE the
+           -- caller can see, and a healthy nightly ingest over an unchanged
+           -- corpus leaves it perfectly still. Named for what it measures after
+           -- task 1003145: the old name, last_indexed_at, promised a liveness
+           -- signal it cannot deliver. Real ingest liveness would need an
+           -- ingest-run ledger, not a proxy on chunk mtimes.
+           --
+           -- ORDER BY … LIMIT 1 rather than MAX(): the same answer on a NOT NULL
+           -- column, but it ASKS for the bounded plan instead of depending on the
+           -- planner's MIN/MAX transform still firing. Scoped with the SAME
+           -- predicate as the search — an unscoped stamp was the freshness half
+           -- of the oracle described above.
+           (SELECT 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
+             ORDER BY updated_at DESC
+             LIMIT 1
+           ) AS last_content_change_at
   `;
   const runner = client || p;
   let rows;
@@ -392,13 +423,13 @@ async function corpusHealth({ builderId, builderRank } = {}, { pool: p = pool, c
     // 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 };
+    return { any_visible: null, any_at_all: null, last_content_change_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,
+    last_content_change_at: r.last_content_change_at || null,
     privileged,
   };
 }
@@ -409,9 +440,11 @@ async function corpusHealth({ builderId, builderRank } = {}, { pool: p = pool, c
 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 };
+  // Never echo the unscoped probe. last_content_change_at is already scoped to
+  // the caller's own view by the query, and is non-null ONLY when any_visible is
+  // true (the same predicate matches nothing in every other state), so in
+  // practice it rides along with no_match and is null on all three bad ones.
+  const safe = { last_content_change_at: (health && health.last_content_change_at) || null };
 
   if (anyVisible === null) {
     return {

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.362",
+  "version": "1.19.363",
   "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

@@ -93,7 +93,17 @@ function renderNoMatch({ q, corpus }) {
       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}.` : '';
+  // "Corpus last changed", NOT "last indexed" — the server derives this from
+  // updated_at on the chunks, and both ingesters delta-gate their upsert, so it
+  // moves when CONTENT changes and stands still through a healthy ingest over an
+  // unchanged corpus. It was labelled "Last indexed:" until task 1003145, which
+  // read as an ingest-liveness signal it was never measuring.
+  //
+  // Both keys are read for the version-skew window: this CLI ships before the
+  // server pin moves, so an OLD server still answers with last_indexed_at. Same
+  // value either way — only the name was wrong.
+  const changedAt = corpus.last_content_change_at || corpus.last_indexed_at;
+  const stamp = changedAt ? ` Corpus last changed: ${changedAt}.` : '';
   if (corpus.healthy) {
     return { stream: 'out', exitCode: 0, lines: [`No matches for "${q}". ${corpus.message}${stamp}`] };
   }

package/scripts/gds/run-unit-tests.js

@@ -107,7 +107,14 @@ const INTEGRATION = new Set([
   // never governs under the widened predicate.
   'government_board_membership_db',
   'government_fold_bench', 'government_live_proof', 'linkify_refs', 'memory_isolation',
-  'memory_pull', 'needs_rebase', 'parallel-load', 'profile_rollup_consent', 'reward_mode_cost_plus_only',
+  'memory_pull', 'needs_rebase', 'parallel-load', 'profile_rollup_consent',
+  // task 1003145: whether the PLANNER uses the migration 225 index for the recall
+  // freshness probe. The DB-free sibling (recall_corpus_health) pins the query
+  // shape and that the migration declares the index; only a real Postgres can
+  // answer whether the probe stops at the first visible row or reads the corpus —
+  // and an unverified claim about exactly that is the comment this task fixed.
+  'recall_freshness_plan_db',
+  'reward_mode_cost_plus_only',
   'scouting_rollup_fanout', 'session_records',
   // task 1003217: the cost-row RAISE against real SQL. Every claim in it IS the
   // SQL — an ON CONFLICT DO UPDATE guarded to move a row only upward, and a

package/src/module-api.js

@@ -1154,8 +1154,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.360 with no explicit bump. run 32883230235. (task 1002620)
 //   1.19.362 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.361 with no explicit bump. run 32886106098. (task 1002620)
+//   1.19.363 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.362 with no explicit bump. run 32889324497. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.362'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.363'; // 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

@@ -122,13 +122,27 @@ test('an outage goes to STDERR with a non-zero exit', () => {
 });
 
 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 corpus = { ...classifyEmptyResult({ any_visible: true, any_at_all: true, privileged: false }), last_content_change_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');
+  assert.match(text, /Corpus last changed: 2026-08-20/, 'freshness is still surfaced');
+  // task 1003145: the stamp comes from chunk updated_at, and both ingesters
+  // delta-gate their upsert — so it moves on CONTENT CHANGE and stands perfectly
+  // still through a healthy ingest of an unchanged corpus. Labelling it "Last
+  // indexed" sold it as ingest liveness, the one thing it cannot report.
+  assert.doesNotMatch(text, /Last indexed/, 'the stamp must not claim to be an ingest-liveness signal');
+});
+
+test('the stamp still renders for an OLD server sending the former key', () => {
+  // Same version-skew reason the no-diagnostic case below is covered: the CLI
+  // ships before the server pin moves, so for a while it talks to a server that
+  // still answers last_indexed_at. Same value, older name — read both.
+  const corpus = { ...classifyEmptyResult({ any_visible: true, any_at_all: true, privileged: false }), last_indexed_at: '2026-08-19T00:00:00.000Z' };
+  const text = renderNoMatch({ q: 'anything', corpus }).lines.join('\n');
+  assert.match(text, /Corpus last changed: 2026-08-19/, 'the older key still renders, under the true label');
 });
 
 test('a server that sends no diagnostic keeps the previous behaviour', () => {
@@ -178,7 +192,28 @@ test('corpusHealth probes EXISTENCE, scoped with the same predicate as the searc
   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');
+  // task 1003145: the freshness probe used to be MAX(updated_at) — an AGGREGATE
+  // over the whole visible corpus, on an unindexed column, while the comment
+  // beside it claimed the path held no scan. ORDER BY … LIMIT 1 over
+  // idx_search_chunks_updated_at (migration 225) stops at the first row that
+  // passes the scope filter instead.
+  assert.doesNotMatch(body, /MAX\(updated_at\)/, 'freshness must not be an aggregate scan');
+  assert.match(body, /ORDER BY updated_at DESC\s+LIMIT 1/, 'it asks for the bounded plan explicitly');
+  const freshness = body.slice(body.indexOf('SELECT updated_at FROM search_chunks'));
+  assert.match(freshness.slice(0, freshness.indexOf('LIMIT 1')), /min_rank = ANY/,
+    'and the freshness probe carries the search’s scope predicate too');
+});
+
+test('the freshness probe has an index to walk (migration 225)', () => {
+  // The LIMIT 1 only bounds anything if updated_at is ORDERED by an index —
+  // otherwise the planner sorts the visible corpus to answer it, which is the
+  // same scan wearing a new name. Migration 103 indexed tsv / body / source /
+  // owner and NOT updated_at, which is how the aggregate went unnoticed.
+  const dir = path.join(ROOT, 'migrations');
+  const sql = fs.readdirSync(dir).filter((f) => /search_chunks/.test(f))
+    .map((f) => fs.readFileSync(path.join(dir, f), 'utf8')).join('\n');
+  assert.match(sql, /CREATE INDEX IF NOT EXISTS idx_search_chunks_updated_at[\s\S]{0,80}\(updated_at DESC\)/,
+    'search_chunks must carry a descending index on updated_at');
 });
 
 test('the route hands the caller ONLY the classifier output', () => {

package/tests/recall_freshness_plan_db.mjs

@@ -0,0 +1,171 @@
+// tests/recall_freshness_plan_db.mjs — task 1003145, against a REAL Postgres.
+//
+// WHY THIS EXISTS BESIDE tests/recall_corpus_health.mjs. That file is DB-free: it
+// pins the SHAPE of the freshness probe (ORDER BY ... LIMIT 1, not an aggregate)
+// and that migration 225 declares an index on updated_at. Neither of those is the
+// claim that actually matters, which is a claim about the DATABASE: that the
+// planner USES that index, so the probe stops at the first visible row instead of
+// reading the visible corpus.
+//
+// That distinction IS the bug being fixed here. The old code said MAX(updated_at)
+// under a comment promising "two index-assisted probes rather than a scan" — a
+// statement about the plan that nothing checked, and that was false. Answering it
+// with only a text tripwire on the SQL would repeat the mistake one level up: the
+// shape can be right while the plan is still a scan (no index, a lost ANALYZE, an
+// ORDER BY the index cannot serve). So this asks the planner directly.
+//
+// It also proves the REWRITE IS SEMANTICALLY IDENTICAL — ORDER BY updated_at DESC
+// LIMIT 1 returns exactly what MAX(updated_at) returned under the same predicate —
+// because the point was to make the probe cheaper, not to change the answer.
+//
+// The SQL under test is SLICED OUT OF modules/memory/search.js rather than copied,
+// so this cannot keep passing against a query the module no longer runs.
+//
+// It SELF-SKIPS (exit 0) with no reachable Postgres, and is listed in
+// run-unit-tests.js INTEGRATION set so the DB-free lane never runs it.
+//
+// Run:  DATABASE_URL=postgres://... node tests/recall_freshness_plan_db.mjs
+//
+// It CREATES its own throwaway search_chunks and drops it again, so point it at a
+// scratch database, never a real one.
+
+import pg from 'pg';
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+import { strict as assert } from 'node:assert';
+
+const ROOT = path.resolve(path.dirname(url.fileURLToPath(import.meta.url)), '..');
+const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL || undefined });
+
+try {
+  await pool.query('SELECT 1');
+} catch (e) {
+  console.log(`recall_freshness_plan_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}). Set DATABASE_URL to run.`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+// Same posture as tests/claims_requested_worktree_db.mjs: this DROPs and CREATEs
+// search_chunks, so refuse anything that looks like a real GDS database.
+const { rows: realRows } = await pool.query(
+  `SELECT to_regclass('public.builders') IS NOT NULL AS has_builders`);
+if (realRows[0].has_builders) {
+  console.log('recall_freshness_plan_db.mjs SKIPPED — this database has a `builders` table, so it is not a scratch DB. It DROPs and CREATEs search_chunks; point it at a throwaway Postgres.');
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.message}`); }
+}
+
+// ---- the query under test, taken from the module itself ----
+
+const searchSrc = fs.readFileSync(path.join(ROOT, 'modules/memory/search.js'), 'utf8');
+const OPEN = '(SELECT updated_at FROM search_chunks';
+const start = searchSrc.indexOf(OPEN);
+assert.ok(start > 0, 'the freshness subquery must be findable in modules/memory/search.js');
+const end = searchSrc.indexOf(') AS last_content_change_at', start);
+assert.ok(end > start, 'the freshness subquery must still be aliased last_content_change_at');
+// Drop the wrapping parens so it stands alone as a statement.
+const FRESHNESS_SQL = searchSrc.slice(start + 1, end);
+assert.match(FRESHNESS_SQL, /ORDER BY updated_at DESC/, 'sanity: sliced the ordered form');
+
+// The privileged caller — the case the task named, where the scope predicate
+// matches nearly every row and the aggregate therefore scanned nearly everything.
+const ALL_RANKS = ['xenos', 'thetes', 'metic', 'archon'];
+const OWNER = 1;
+
+async function explain(sql) {
+  const { rows } = await pool.query(`EXPLAIN (FORMAT JSON) ${sql}`, [ALL_RANKS, OWNER]);
+  return JSON.stringify(rows[0]['QUERY PLAN']);
+}
+
+// ---- fixture ----
+
+await pool.query('DROP TABLE IF EXISTS search_chunks');
+// Only the columns this probe touches. The real table (migration 103) carries the
+// tsvector, the trigram body and the rest; none of them participate in this plan.
+await pool.query(`
+  CREATE TABLE search_chunks (
+    id               bigserial PRIMARY KEY,
+    min_rank         text NOT NULL DEFAULT 'xenos',
+    owner_builder_id bigint,
+    updated_at       timestamptz NOT NULL DEFAULT now()
+  )`);
+// Enough rows that a sequential scan plus a top-N sort is visibly the worse plan.
+await pool.query(`
+  INSERT INTO search_chunks (min_rank, owner_builder_id, updated_at)
+  SELECT (ARRAY['xenos','thetes','metic','archon'])[1 + (i % 4)],
+         CASE WHEN i % 50 = 0 THEN 1 + (i % 7) ELSE NULL END,
+         now() - (i || ' minutes')::interval
+    FROM generate_series(1, 20000) AS i`);
+await pool.query('ANALYZE search_chunks');
+
+await test('WITHOUT the index the probe is the scan the old comment denied', async () => {
+  const plan = await explain(FRESHNESS_SQL);
+  assert.match(plan, /Seq Scan/, 'baseline: with no index on updated_at this reads the table');
+  assert.doesNotMatch(plan, /idx_search_chunks_updated_at/, 'and cannot be using an index that does not exist yet');
+});
+
+await test('migration 225 applies cleanly', async () => {
+  const sql = fs.readFileSync(path.join(ROOT, 'migrations/core_225_search_chunks_updated_at_idx.sql'), 'utf8');
+  await pool.query(sql);
+  await pool.query('ANALYZE search_chunks');
+  const { rows } = await pool.query(
+    `SELECT 1 FROM pg_indexes WHERE tablename = 'search_chunks' AND indexname = 'idx_search_chunks_updated_at'`);
+  assert.equal(rows.length, 1, 'the migration must create idx_search_chunks_updated_at');
+});
+
+await test('WITH the index the planner walks it and stops — no scan', async () => {
+  // THE CLAIM THE COMMENT MAKES. Everything else in this file is scaffolding for
+  // this assertion: the probe must reach its answer through the index, not by
+  // reading the visible corpus.
+  const plan = await explain(FRESHNESS_SQL);
+  assert.match(plan, /idx_search_chunks_updated_at/, 'the freshness probe must use the updated_at index');
+  assert.match(plan, /Index Scan/, 'and reach it by an index scan');
+  assert.doesNotMatch(plan, /Seq Scan/, 'no sequential scan may remain on this path');
+  assert.doesNotMatch(plan, /"Node Type":"Sort"/, 'and no sort — the index already supplies the order');
+});
+
+await test('the probe reads a bounded number of rows, not the corpus', async () => {
+  const { rows } = await pool.query(
+    `EXPLAIN (ANALYZE, FORMAT JSON) ${FRESHNESS_SQL}`, [ALL_RANKS, OWNER]);
+  const plan = rows[0]['QUERY PLAN'][0].Plan;
+  // A privileged caller matches nearly every row, so the first row the index hands
+  // back already passes the filter. That is the inversion this index buys: the
+  // worst case for the old aggregate is the best case for this plan.
+  assert.ok(plan['Actual Rows'] <= 1, `expected at most 1 row out, got ${plan['Actual Rows']}`);
+  const read = JSON.stringify(plan).match(/"Actual Rows": ?(\d+)/g).map((m) => Number(m.split(':')[1]));
+  assert.ok(Math.max(...read) < 100, `plan should touch a handful of rows, not 20000 (saw ${Math.max(...read)})`);
+});
+
+await test('the rewrite returns exactly what MAX(updated_at) returned', async () => {
+  // The point was to make the probe cheaper, NOT to change the answer. Equivalent
+  // on a NOT NULL column, and this pins it rather than trusting the reasoning.
+  const { rows: viaOrder } = await pool.query(FRESHNESS_SQL, [ALL_RANKS, OWNER]);
+  const { rows: viaMax } = await pool.query(
+    `SELECT MAX(updated_at) AS updated_at FROM search_chunks
+      WHERE min_rank = ANY($1::text[])
+        AND (owner_builder_id IS NULL OR owner_builder_id = $2::bigint)`, [ALL_RANKS, OWNER]);
+  assert.equal(String(viaOrder[0].updated_at), String(viaMax[0].updated_at));
+});
+
+await test('a caller who can see NOTHING still gets null, not a wrong stamp', async () => {
+  // The scope predicate is load-bearing (ADR 0016): a freshness stamp that outran
+  // the caller scope would be the freshness half of the oracle this diagnostic was
+  // rewritten to remove. No visible row must mean no stamp.
+  const { rows } = await pool.query(FRESHNESS_SQL, [['nobody'], 999999]);
+  assert.equal(rows.length, 0, 'nothing visible must yield no row, hence a null stamp');
+});
+
+await pool.query('DROP TABLE IF EXISTS search_chunks');
+await pool.end();
+
+console.log('');
+console.log(`recall_freshness_plan_db: ${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);