@bongos/core 1.19.361 → 1.19.363

package/modules/hall-ui/public/government.js

@@ -25,14 +25,21 @@
 // gated server-side on the `government.manage` atom (archon floor). On 401 →
 // web sign-in.
 //
-// SINCE R15 (goal 1000069, ADR 0175) this page carries the three-section IA —
-// Constitution · Board Room · Ranks & Permissions — because Government is the
-// page that answers "how is this project governed", and administration is only
-// the third part of that answer. Tabs are OTBKit.makeTabs with hash deep links
-// (#constitution / #board-room / #ranks). The first two sections are FRAMES
-// until their build-out lands: R18 fills Constitution with the live values +
-// change history, R19 adds the charter library, R16/R17 fill the Board Room
-// with open items and the vote. Until then each frame states what belongs there
+// SINCE R15 (goal 1000069, ADR 0175) this page carries a three-section IA,
+// because Government is the page that answers "how is this project governed"
+// and administration is only one part of that answer. Task 1003269 reordered
+// the tabs to Permissions · Board Room · Constitution (the administering Archon
+// works from the first of those, and it used to sit last) and shortened the
+// "Ranks & Permissions" label to "Permissions". Tabs are OTBKit.makeTabs with
+// hash deep links, and the HASH IDS DID NOT CHANGE with that reorder
+// (#constitution / #board-room / #ranks) — they are linked from Discord and
+// docs.
+//
+// The Constitution and Board Room sections began as FRAMES (named here by
+// section, not by position, so a reorder like 1003269's cannot make this
+// comment lie): R18 filled Constitution with the live values + change history,
+// R19 added the charter library, and R16/R17 filled the Board Room with open
+// items and the vote. Until a frame is filled it states what belongs there
 // and shows an honest kit empty state — never a fake or a hardcoded value that
 // could drift from the real config.
 
@@ -412,19 +419,29 @@
 
   // ---- the three-section IA (R15) -------------------------------------------
 
-  // Tab order is the spec's — Constitution · Board Room · Ranks & Permissions.
-  // A non-archon lands on the Constitution (the page's IA claim: this is the
-  // page that answers "how is this project governed"); the Archon still lands
-  // on Ranks, their working surface.
+  // Tab order puts Permissions FIRST (task 1003269, owner request): it is the
+  // surface an administering Archon actually works from, and it sat last. The
+  // label is "Permissions" — the words the owner uses for it — not the compound
+  // "Ranks & Permissions"; ranks are still what the panel lists, but permissions
+  // are the atom (ADR 0151) and the shorter label is the clearer one.
+  //
+  // THE HASH IDS ARE LOAD-BEARING AND MUST NOT CHANGE: the Discord board
+  // announcement deep-links ?item=<id>#board-room (board-broadcast.js, and the
+  // reader in loadBoard below), and #constitution/#ranks are linked from docs.
+  // Reorder and relabel freely; the ids are the contract.
+  //
+  // A non-archon still lands on the Constitution (the page's IA claim: this is
+  // the page that answers "how is this project governed"); the Archon still
+  // lands on their working surface, which is now also the first tab.
   function wireTabs({ isArchon }) {
     window.OTBKit.makeTabs({
       mount: document.getElementById('gov-tabs'),
       hash: true,
       initial: isArchon ? 'ranks' : 'constitution',
       tabs: [
-        { id: 'constitution', label: 'Constitution', panel: 'gov-panel-constitution' },
+        { id: 'ranks', label: 'Permissions', panel: 'gov-panel-ranks' },
         { id: 'board-room', label: 'Board Room', panel: 'gov-panel-board' },
-        { id: 'ranks', label: 'Ranks & Permissions', panel: 'gov-panel-ranks' },
+        { id: 'constitution', label: 'Constitution', panel: 'gov-panel-constitution' },
       ],
     });
   }
@@ -843,15 +860,16 @@
   }
 
   // Since R16 the page shell admits page.view.government (metic+), and only the
-  // RANKS tab is the archon admin surface — so the seal narrowed from the whole
-  // page to that one panel. Cosmetic defence-in-depth as ever: every
+  // Permissions tab (panel id gov-panel-ranks) is the archon admin surface — so
+  // the seal narrowed from the whole page to that one panel. Cosmetic
+  // defence-in-depth as ever: every
   // /government/* CRUD endpoint still gates on government.manage server-side,
   // and the board read carries its own atom.
   function sealRanksPanel() {
     const panel = document.getElementById('gov-panel-ranks');
     const body = document.getElementById('gov-body');
     // Replace the admin surface with the sealed note, inside its own tab only.
-    panel.innerHTML = '<p class="gov-sealed">Ranks & Permissions is the Archon administration surface. The Constitution and the Board Room are yours to read.</p>';
+    panel.innerHTML = '<p class="gov-sealed">Permissions is the Archon administration surface. The Constitution and the Board Room are yours to read.</p>';
     body.hidden = false;
   }
 

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.361",
+  "version": "1.19.363",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.361",
+      "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.361",
+  "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

@@ -1152,8 +1152,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.359 with no explicit bump. run 32881040669. (task 1002620)
 //   1.19.361 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         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.361'; // 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/hall_page_gate_map.mjs

@@ -68,10 +68,11 @@ const ORACLE = {
   '/builders/scouting': 'requireProjectCuratePage',
 
   // Metic+ since R16 (goal 1000069): the Government page is three rooms —
-  // Constitution · Board Room · Ranks & Permissions — and only the third is the
-  // archon admin surface, whose DATA routes all still gate on government.manage
-  // individually. The shell follows the widest legitimate audience; the board
-  // reads carry the vote atom, the manage tab seals itself for non-archons.
+  // Permissions · Board Room · Constitution (reordered, task 1003269) — and only
+  // the Permissions room is the archon admin surface, whose DATA routes all still
+  // gate on government.manage individually. The shell follows the widest
+  // legitimate audience; the board reads carry the vote atom, and the manage
+  // tab seals itself for non-archons.
   '/builders/government': 'requireGovernmentPage',
 
   // Deliberately UNGATED — the landing card, the rank ladder, the reward

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);