@dotdrelle/wiki-manager 0.15.97 → 0.15.99

package/src/core/runtimeEventAdapter.js

@@ -23,6 +23,19 @@ export function mapRuntimeEvent(event) {
       const content = String(event?.content ?? event?.message ?? '').trim();
       return content ? [{ type: 'assistant_message', payload: { content } }] : [];
     }
+    // Progressive final stream (lot 7). The gateway only streams the MAIN
+    // assembly, never a role, so a delta can only belong to the answer. The
+    // reducer replaces the streamed text with the final `assistant_message`
+    // (finalizeAssistantMessage), so streaming cannot duplicate it.
+    case 'assistant_delta': {
+      const delta = String(event?.delta ?? '');
+      return delta ? [{ type: 'assistant_delta', payload: { delta } }] : [];
+    }
+    // A tool call interrupted the streamed answer: the text so far was
+    // reasoning, not the answer — discard it (the reducer empties, never pops,
+    // the streaming entry).
+    case 'assistant_delta_reset':
+      return [{ type: 'assistant_delta_reset', payload: {} }];
     case 'tool_started':
       return log(`tool ${toolLabel(event)} started`);
     case 'tool_finished': {
@@ -60,17 +73,102 @@ export function mapRuntimeEvent(event) {
         },
       }];
     }
+    // ── Activity (lot 2) ────────────────────────────────────────────────────
+    //
+    // The runtime's phases enrich the EXISTING business activity line; they do
+    // not open a second axis of "phases" beside `projectWorkflow`. That is why
+    // they travel as runtime_log here and are aggregated downstream, rather
+    // than minting a new event type the reducer would have to reconcile.
+    case 'phase_started':
+      return log(`phase ${phaseLabel(event)} started`);
+    case 'phase_finished': {
+      const counters = phaseCounters(event);
+      const outcome = event?.ok === false ? 'interrupted' : 'done';
+      return log(`phase ${phaseLabel(event)} ${outcome}${counters}`);
+    }
+    case 'progress': {
+      const label = String(event?.label ?? event?.phase ?? '').trim();
+      return label ? log(`progress ${label}${phaseCounters(event)}`) : [];
+    }
+    // A heartbeat is liveness, not history: it proves the run is alive to
+    // whoever is watching right now. It travels as its own NON-persisted event
+    // so the run strip can read it, but it never reaches the journal — one
+    // line per beat would bury what actually happened. Persisting is the
+    // store's decision (NON_PERSISTED_EVENT_TYPES); dropping it here would
+    // leave the strip with no liveness signal at all.
+    case 'heartbeat':
+      return [{
+        type: 'runtime_heartbeat',
+        payload: { elapsedMs: Number(event?.elapsedMs) || 0 },
+      }];
+    case 'finding': {
+      const severity = String(event?.severity ?? '').trim();
+      const summary = String(event?.summary ?? '').trim();
+      if (!summary) return [];
+      const path = String(event?.path ?? '').trim();
+      const where = path ? ` at ${path}` : '';
+      return log(`finding${severity ? ` [${severity}]` : ''} from ${String(event?.role ?? 'runtime')}${where}: ${summary}`);
+    }
+    // Maintenance the gateway performed on its own memory (eviction of an
+    // inactive workspace, compaction of a thread). Not a failure — a notice,
+    // so a reader can tell "the agent forgot an old workspace" from "the
+    // agent broke".
+    case 'notice': {
+      const topic = String(event?.topic ?? 'notice').trim();
+      const detail = String(event?.detail ?? '').trim();
+      return log(`notice ${topic}${detail ? `: ${detail}` : ''}`);
+    }
+    // A degradation must announce itself — that is the whole contract. It is
+    // never filtered, whatever else this adapter decides to keep quiet.
+    case 'degraded': {
+      const capability = String(event?.capability ?? 'capability').trim();
+      const cause = String(event?.cause ?? 'unknown cause').trim();
+      const fallback = String(event?.fallback ?? '').trim();
+      return log(`degraded ${capability}: ${cause}${fallback ? ` — ${fallback}` : ''}`);
+    }
     case 'run_started':
     case 'run_created':
     case 'agent_thinking':
     case 'run_completed':
     case 'run_failed':
     case 'run_cancelled':
-    default:
+      // Deliberately silent, and listed BY NAME so the silence is a decision
+      // rather than a default: `agent_thinking` is private reasoning the chat
+      // never shows, and the terminal events are already carried by the
+      // dispatcher's own `status()` poll.
       return [];
+    default:
+      // Everything else is a type this manager does not know — most likely a
+      // newer gateway talking to an older manager. Dropping it made that
+      // version skew invisible: the events simply never arrived, and nothing
+      // said so. One bounded line is the cost of knowing.
+      return log(`unrecognized runtime event "${type || 'unnamed'}"${unknownDetail(event)}`);
   }
 }
 
+function phaseLabel(event) {
+  return String(event?.phase ?? event?.label ?? 'unnamed');
+}
+
+function phaseCounters(event) {
+  const parts = [];
+  const tools = Number(event?.tools);
+  const pages = Number(event?.pages);
+  if (Number.isFinite(tools) && tools > 0) parts.push(`${tools} tool(s)`);
+  if (Number.isFinite(pages) && pages > 0) parts.push(`${pages} page(s) read`);
+  return parts.length > 0 ? ` — ${parts.join(', ')}` : '';
+}
+
+// Bounded on purpose: this is a diagnostic breadcrumb for a version skew, not
+// a channel for an unknown payload to reach the journal whole.
+const UNKNOWN_EVENT_DETAIL_MAX = 200;
+function unknownDetail(event) {
+  const keys = Object.keys(event ?? {})
+    .filter((key) => !['type', 'runId', 'ts', 'sequence'].includes(key));
+  if (keys.length === 0) return '';
+  return ` (fields: ${keys.join(', ')})`.slice(0, UNKNOWN_EVENT_DETAIL_MAX);
+}
+
 function log(message) {
   return [{ type: 'runtime_log', payload: { message } }];
 }

package/src/core/runtimeEventAdapter.test.js

@@ -61,6 +61,96 @@ test('private reasoning and terminal events are never re-emitted', () => {
   assert.deepEqual(mapRuntimeEvent({ type: 'run_cancelled' }), []);
 });
 
-test('an unknown event type produces nothing', () => {
-  assert.deepEqual(mapRuntimeEvent({ type: 'made_up' }), []);
+// (An unknown type used to produce nothing. It now produces one journal line —
+// see "an unknown event type is journalled instead of vanishing" below. The
+// old assertion pinned the silence that hid a version skew.)
+
+// ── Activity events (lot 2) ──────────────────────────────────────────────────
+
+test('phase and progress events enrich the journal with bounded counters', () => {
+  assert.deepEqual(
+    mapRuntimeEvent({ type: 'phase_started', phase: 'discover' }),
+    [{ type: 'runtime_log', payload: { message: 'phase discover started' } }],
+  );
+  const [finished] = mapRuntimeEvent({
+    type: 'phase_finished', phase: 'discover', ok: true, tools: 7, pages: 4,
+  });
+  assert.match(finished.payload.message, /phase discover done — 7 tool\(s\), 4 page\(s\) read/);
+
+  const [interrupted] = mapRuntimeEvent({ type: 'phase_finished', phase: 'critique', ok: false });
+  assert.match(interrupted.payload.message, /phase critique interrupted/);
+});
+
+// A beat proves the run is alive to whoever watches NOW. It still travels — as
+// its own non-persisted event, so the run strip can read it — but one journal
+// line per beat would bury what actually happened under "still alive".
+test('a heartbeat becomes a non-persisted liveness event, not a journal line', () => {
+  assert.deepEqual(
+    mapRuntimeEvent({ type: 'heartbeat', elapsedMs: 30_000 }),
+    [{ type: 'runtime_heartbeat', payload: { elapsedMs: 30_000 } }],
+  );
+});
+
+test('a finding carries its severity, its author and its path', () => {
+  const [entry] = mapRuntimeEvent({
+    type: 'finding',
+    role: 'critique',
+    severity: 'blocking',
+    path: 'wiki/concepts/demo/a.md',
+    summary: 'cites no source',
+  });
+  assert.match(
+    entry.payload.message,
+    /finding \[blocking\] from critique at wiki\/concepts\/demo\/a\.md: cites no source/,
+  );
+});
+
+test('a degradation is never filtered', () => {
+  const [entry] = mapRuntimeEvent({
+    type: 'degraded',
+    capability: 'role:critique',
+    cause: 'model timeout',
+    fallback: 'the run continues without this role',
+  });
+  assert.match(entry.payload.message, /degraded role:critique: model timeout — the run continues/);
+});
+
+/*
+ The version-skew guard. A newer gateway talking to an older manager used to
+ lose EVERY new event here, silently — the adapter ended on `default: return []`.
+ The deliberate silences stay silent, but they are now listed by name, so the
+ difference between "we chose not to show this" and "we did not recognise it"
+ is visible in the journal instead of being the same thing.
+*/
+test('an unknown event type is journalled instead of vanishing', () => {
+  const [entry] = mapRuntimeEvent({ type: 'sub_phase_started', detail: 'x', weight: 2 });
+  assert.equal(entry.type, 'runtime_log');
+  assert.match(entry.payload.message, /unrecognized runtime event "sub_phase_started"/);
+  assert.match(entry.payload.message, /fields: detail, weight/);
+});
+
+test('the deliberate silences stay silent', () => {
+  for (const type of ['agent_thinking', 'run_started', 'run_completed', 'run_failed', 'run_cancelled']) {
+    assert.deepEqual(mapRuntimeEvent({ type }), [], `${type} must stay silent`);
+  }
+});
+
+test('a memory notice is journalled as maintenance, not as a failure', () => {
+  const [entry] = mapRuntimeEvent({
+    type: 'notice', topic: 'memory.evicted', detail: 'old-workspace',
+  });
+  assert.equal(entry.type, 'runtime_log');
+  assert.match(entry.payload.message, /^notice memory\.evicted: old-workspace$/);
+});
+
+test('the final stream maps as deltas, and a reset clears them', () => {
+  assert.deepEqual(
+    mapRuntimeEvent({ type: 'assistant_delta', delta: 'Hi' }),
+    [{ type: 'assistant_delta', payload: { delta: 'Hi' } }],
+  );
+  assert.deepEqual(
+    mapRuntimeEvent({ type: 'assistant_delta_reset' }),
+    [{ type: 'assistant_delta_reset', payload: {} }],
+  );
+  assert.deepEqual(mapRuntimeEvent({ type: 'assistant_delta', delta: '' }), []);
 });

package/src/core/skillCompiler.test.js

@@ -31,7 +31,7 @@ test('validation rejects technical routing details', () => {
 });
 
 test('every shipped scaffold skill compiles to a single intention, deterministically', async () => {
-  const expected = { pipeline: 1, 'wiki-sync': 1, 'wiki-ingest': 1, 'wiki-build': 1, deliver: 1, diagnose: 1, status: 1, 'new-template': 1, 'wiki-rebuild': 1 };
+  const expected = { pipeline: 1, 'wiki-sync': 1, 'wiki-ingest': 1, 'wiki-build': 1, deliver: 1, diagnose: 1, status: 1, 'new-template': 1, 'wiki-rebuild': 1, curate: 1 };
   // Passing no llmFallback used to make this test assert the one path
   // production never takes: an ambiguous body silently returns the safe
   // mono-intention fallback, so the count was 1 and the test was green while

package/src/core/testGate.test.js

@@ -0,0 +1,33 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+
+// The `npm test` argument list is hand-maintained, and it has drifted twice:
+// four files were once found outside the gate, and mcpEndpoints.test.js was
+// green on disk while nothing ran it. A test nobody runs is worse than no
+// test — it reads as coverage. This is the check that says so.
+test('every test file on disk is in the npm test gate', () => {
+  const pkg = JSON.parse(readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
+  const listed = new Set(
+    pkg.scripts.test.split(/\s+/).filter((argument) => argument.endsWith('.test.js')),
+  );
+  const onDisk = execFileSync('find', ['src', '-name', '*.test.js'], {
+    cwd: repoRoot,
+    encoding: 'utf8',
+  })
+    .trim()
+    .split('\n')
+    .filter(Boolean)
+    .sort();
+
+  const missing = onDisk.filter((file) => !listed.has(file));
+  assert.deepEqual(missing, [], `test files not run by \`npm test\`:\n${missing.join('\n')}`);
+
+  const stale = [...listed].filter((file) => !onDisk.includes(file));
+  assert.deepEqual(stale, [], `\`npm test\` names files that no longer exist:\n${stale.join('\n')}`);
+});

package/src/core/toolLoop.js

@@ -1,3 +1,5 @@
+import { truncateToolResult } from './mcp.js';
+
 // Minimal, side-effect-free bounded tool-use loop.
 //
 // This is the shared mechanic of "ask the LLM with a tool set, run the tool
@@ -79,9 +81,13 @@ export async function runBoundedToolLoop({
     convo.push(result.message ?? { role: 'assistant', content: result.content ?? '', tool_calls: calls });
     // Tool calls within one turn are independent: dispatch concurrently, then
     // replay results in the model's call order so the transcript stays stable.
+    // Bound what enters the LLM context, exactly like the /agent loop
+    // (graph.js). Without it a wide read — a CME Confluence search at limit 50
+    // can weigh ~35 kB — is re-sent on every iteration (up to the cap), and the
+    // chat answer pays for tokens the model never needed.
     const outcomes = await Promise.all(calls.map(async (call) => ({
       tool_call_id: call.id,
-      content: await executeCall(call),
+      content: truncateToolResult(await executeCall(call)),
     })));
     for (const outcome of outcomes) {
       convo.push({ role: 'tool', tool_call_id: outcome.tool_call_id, content: outcome.content });
@@ -129,7 +135,13 @@ async function finalAnswerWithoutTools({
     });
     if (result?.tool_calls?.length) return '';
     return String(result?.content ?? result?.message?.content ?? '').trim();
-  } catch {
+  } catch (err) {
+    // An abort is the user cancelling, not an empty answer. Swallowing it here
+    // made `runBoundedToolLoop` return `{ content: '', capped: true }`, and the
+    // caller printed the iteration-limit notice for a turn that was cancelled
+    // — the loop's contract is that an abort escapes, and this was the one
+    // call that broke it.
+    if (err?.name === 'AbortError' || signal?.aborted) throw err;
     return '';
   }
 }

package/src/core/toolLoop.test.js

@@ -104,6 +104,34 @@ test('answers from the gathered results when the cap is reached', async () => {
   assert.equal(out.content, "Voici ce que j'ai trouvé.");
 });
 
+test('bounds a wide tool result before it enters the LLM context', async () => {
+  // A CME Confluence search at limit 50 can weigh ~35 kB and would otherwise be
+  // re-sent on every iteration. The /agent loop already truncates at 16 kB
+  // (graph.js); the chat loop must not be the one unbounded path.
+  let round = 0;
+  let toolContent = '';
+  const llm = {
+    async completeWithTools({ messages }) {
+      round += 1;
+      if (round === 1) {
+        const calls = [toolCall('c1', 'cme__cme_confluence_search')];
+        return { message: { role: 'assistant', content: '', tool_calls: calls }, tool_calls: calls };
+      }
+      toolContent = messages.find((m) => m.role === 'tool')?.content ?? '';
+      return { content: 'ok', tool_calls: [] };
+    },
+  };
+  const wide = 'x'.repeat(50000);
+  await runBoundedToolLoop({
+    llm,
+    tools: [{ function: { name: 'cme__cme_confluence_search' } }],
+    executeCall: async () => wide,
+  });
+  assert.ok(toolContent.length < wide.length, 'the result must be bounded');
+  assert.ok(toolContent.length <= 16200, `bounded length was ${toolContent.length}`);
+  assert.match(toolContent, /tronqu/);
+});
+
 test('propagates an abort thrown by executeCall', async () => {
   const llm = {
     async completeWithTools() {

package/src/orchestrator/dispatcher.js

@@ -255,6 +255,7 @@ async function executeExternalRuntime(task, assignment, {
       capability: task.requiredCapability ?? null,
       arguments: task.arguments && typeof task.arguments === 'object' ? task.arguments : {},
       workspace: workspaceRequest(session),
+      memoryScope: memoryScopeRequest(session),
       model: activeProfileModel(session),
       language: session?.language ?? session?.wikircConfig?.language ?? null,
       mcp: mcpPool,
@@ -471,6 +472,24 @@ function executeRequest(task, session, runId, assignment) {
   };
 }
 
+/**
+ * Which past conversation this run resumes, on the external runtime.
+ *
+ * The workspace alone today. The multi-user lot turns this into
+ * `<workspace>:<actorId>` — the shape is already the one the gateway accepts,
+ * so identity lands here and nowhere else. Returning null is legitimate and
+ * silent: the gateway then scopes to the workspace it resolved itself.
+ *
+ * Never a value a caller supplied: the runtime treats the scope as a read
+ * capability and refuses one that leaves its own workspace.
+ */
+function memoryScopeRequest(session) {
+  const actorId = session?._currentRunIdentity?.actorId ?? session?.actorId ?? null;
+  if (!actorId) return null;
+  const workspace = workspaceRequest(session)?.name;
+  return workspace ? `${workspace}:${String(actorId)}` : null;
+}
+
 function workspaceRequest(session) {
   const workspace = session.workspace ?? session._currentRunIdentity?.workspace;
   if (workspace && typeof workspace === 'object' && !Array.isArray(workspace)) return { ...workspace };

package/src/orchestrator/knowledgeSignals.js

@@ -0,0 +1,260 @@
+import { createHash } from 'node:crypto';
+import { closeSync, existsSync, openSync, readFileSync, readSync, readdirSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+
+/*
+ Deterministic corpus signals: what the LIVE wiki says about itself, with no
+ model and no ingest plan in the loop.
+
+ `detectConceptSplits` only ever saw the current ingest plan, and
+ `subjectMatchInventory` builds a prompt context without producing a
+ persistent diagnosis — so two homonym leaves already written under one concept
+ folder were invisible until now. This reads the corpus on disk and reports the
+ paths, nothing else.
+*/
+
+// Case, accents and punctuation are not meaning.
+export function normalizeSubject(value) {
+  return String(value ?? '')
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * Two homonym leaves under one concept are ONE conflict. The result is bounded
+ * for display, but `total` counts the whole set and `dropped` names what the
+ * ceiling hid — a silent cap would also freeze the fingerprint below.
+ */
+export function detectConceptConflicts(leaves, { max = 50 } = {}) {
+  const groups = new Map();
+  for (const leaf of leaves ?? []) {
+    const concept = String(leaf?.concept ?? '').trim();
+    const subject = normalizeSubject(leaf?.subject);
+    const path = String(leaf?.path ?? '').trim();
+    if (!concept || !subject || !path) continue;
+    const key = `${concept}\u0000${subject}`;
+    const group = groups.get(key) ?? { concept, subject, paths: [] };
+    group.paths.push(path);
+    groups.set(key, group);
+  }
+  const all = [...groups.values()]
+    .map((group) => ({ ...group, paths: [...new Set(group.paths)].sort() }))
+    .filter((group) => group.paths.length > 1)
+    .sort((a, b) => a.concept.localeCompare(b.concept) || a.subject.localeCompare(b.subject));
+  const conflicts = all.slice(0, max);
+  return { conflicts, total: all.length, dropped: all.length - conflicts.length };
+}
+
+/**
+ * A stable version for the trigger. `total` participates on purpose: a 51st
+ * conflict appearing later must MOVE the fingerprint even though it is beyond
+ * the display ceiling — otherwise it would dedup as already-seen and the corpus
+ * could degrade with no review.
+ */
+export function conflictFingerprint(conflicts, total = Array.isArray(conflicts) ? conflicts.length : 0) {
+  const lines = (conflicts ?? [])
+    .map((conflict) => `${conflict.concept}/${conflict.subject}:${[...conflict.paths].sort().join('|')}`)
+    .sort();
+  lines.push(`total:${total}`);
+  return createHash('sha1').update(lines.join('\n')).digest('hex').slice(0, 16);
+}
+
+function frontmatterSubject(raw) {
+  if (!raw || !raw.startsWith('---')) return null;
+  const end = raw.indexOf('\n---', 3);
+  if (end === -1) return null;
+  try {
+    const data = parseYaml(raw.slice(3, end)) ?? {};
+    const subject = data.subject ?? data.title;
+    return subject == null ? null : String(subject);
+  } catch {
+    return null;
+  }
+}
+
+// The frontmatter is at the top of the file; reading a whole page to look at
+// its header is the cost the manager cannot pay synchronously on its event
+// loop (the same reason llm-wiki's sidebar reads a bounded head).
+function readFileHead(filePath, maxBytes = 4_096) {
+  let handle;
+  try {
+    handle = openSync(filePath, 'r');
+    const buffer = Buffer.allocUnsafe(maxBytes);
+    const bytes = readSync(handle, buffer, 0, maxBytes, 0);
+    return buffer.toString('utf8', 0, bytes);
+  } catch {
+    return null;
+  } finally {
+    if (handle !== undefined) {
+      try { closeSync(handle); } catch { /* already gone */ }
+    }
+  }
+}
+
+/**
+ * Every `.md` under `wiki/concepts/`, with its top-level concept folder, its
+ * subject (frontmatter `subject`, else the file name) and its path RELATIVE to
+ * `wiki/concepts/` — nested folders included, so two leaves in different
+ * sub-folders still report two DISTINCT paths.
+ */
+/**
+ * The engine's source registry (`.wiki/source-registry.json`), read as the
+ * stable contract it is. Unreadable or corrupt yields no sources: a failed
+ * observation never breaks the run that triggered it.
+ */
+export function readSourceRegistry(rootDir) {
+  let raw;
+  try {
+    raw = readFileSync(join(String(rootDir), '.wiki', 'source-registry.json'), 'utf8');
+  } catch {
+    return { sources: [] };
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    return { sources: Array.isArray(parsed?.sources) ? parsed.sources : [] };
+  } catch {
+    return { sources: [] };
+  }
+}
+
+/**
+ * Every `.md` under `wiki/`, relative to the workspace — the inventory the
+ * engine's `reconcileRegistry` calls `wikiPages`. Names only, no content.
+ */
+export function readWikiPages(rootDir, { max = 5_000 } = {}) {
+  const base = join(String(rootDir), 'wiki');
+  const pages = [];
+  let entries;
+  try {
+    entries = readdirSync(base, { withFileTypes: true, recursive: true });
+  } catch {
+    return pages;
+  }
+  const toPosix = (value) => value.split(sep).join('/');
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    const parent = entry.parentPath ?? entry.path;
+    if (!parent) continue;
+    const rel = toPosix(relative(base, join(parent, entry.name)));
+    if (!rel || rel.startsWith('..')) continue;
+    pages.push(`wiki/${rel}`);
+    if (pages.length >= max) break;
+  }
+  return pages.sort();
+}
+
+// The engine's `orphanPages` rule: a page no ACTIVE source lists among the pages
+// it produced. A hand-written or pre-registry page is an orphan too — a
+// provenance gap the operator is asked about, never a deletion.
+function orphanPagesFromRegistry(registry, wikiPages) {
+  const supported = new Set(
+    (registry?.sources ?? [])
+      .filter((source) => String(source?.status ?? 'active') === 'active')
+      .flatMap((source) => (Array.isArray(source?.producedPages) ? source.producedPages.map(String) : [])),
+  );
+  return wikiPages.map(String).filter((page) => !supported.has(page)).sort();
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * The registry's own deterministic staleness facts, with no rule to mirror:
+ *
+ * - `aged` — an active source whose `lastIngestedAt` (the engine writes it) is
+ *   older than the window. A source never ingested (`null`) is not "aging
+ *   knowledge", it simply produced none;
+ * - `vanished-archive` / `vanished-page` — the registry names a path that no
+ *   longer exists. Existence is existence: this is the engine's
+ *   `reconcileRegistry` truth, reached without re-implementing its rules.
+ *
+ * (Orphans — a wiki page no active source backs — need the full wiki inventory
+ * and the supported-set rule; that one stays the engine's to expose.)
+ * Bounded like the conflict scan: `total` counts the whole set.
+ */
+export function detectStaleKnowledge(registry, {
+  rootDir = '',
+  now = Date.now(),
+  staleAfterDays = 180,
+  max = 50,
+  exists = existsSync,
+  // The `wiki/**/*.md` inventory (`readWikiPages`), when the caller has it:
+  // orphan detection is a join on the registry, nothing more.
+  wikiPages = null,
+} = {}) {
+  const cutoff = Number(now) - staleAfterDays * DAY_MS;
+  const evidence = [];
+  // Counted per kind over the FULL set: the ceiling line must describe the
+  // facts it is capping, not lump natures into one number. "61 source(s) not
+  // re-verified" sent the reader looking for the wrong defect.
+  const counts = { aged: 0, vanishedArchive: 0, vanishedPage: 0, orphan: 0 };
+  for (const source of registry?.sources ?? []) {
+    if (String(source?.status ?? 'active') !== 'active') continue;
+    const sourceId = String(source?.sourceId ?? '');
+    const archivePath = String(source?.archivePath ?? '');
+    if (archivePath && !exists(join(String(rootDir), archivePath))) {
+      evidence.push({ kind: 'vanished-archive', sourceId, path: archivePath });
+      counts.vanishedArchive += 1;
+    }
+    for (const page of source?.producedPages ?? []) {
+      const pagePath = String(page ?? '');
+      if (pagePath && !exists(join(String(rootDir), pagePath))) {
+        evidence.push({ kind: 'vanished-page', sourceId, path: pagePath });
+        counts.vanishedPage += 1;
+      }
+    }
+    const lastIngestedAt = source?.lastIngestedAt ?? null;
+    const observed = Date.parse(String(lastIngestedAt ?? ''));
+    if (Number.isFinite(observed) && observed <= cutoff) {
+      evidence.push({ kind: 'aged', sourceId, path: archivePath, lastIngestedAt });
+      counts.aged += 1;
+    }
+  }
+  if (Array.isArray(wikiPages)) {
+    for (const page of orphanPagesFromRegistry(registry, wikiPages)) {
+      evidence.push({ kind: 'orphan', sourceId: null, path: page });
+      counts.orphan += 1;
+    }
+  }
+  evidence.sort((a, b) => a.kind.localeCompare(b.kind)
+    || a.path.localeCompare(b.path)
+    || String(a.sourceId ?? '').localeCompare(String(b.sourceId ?? '')));
+  const stale = evidence.slice(0, max);
+  return { stale, total: evidence.length, dropped: evidence.length - stale.length, counts };
+}
+
+export function staleFingerprint(stale, total = Array.isArray(stale) ? stale.length : 0) {
+  const lines = (stale ?? [])
+    .map((entry) => `${entry.kind}:${entry.sourceId}:${entry.path}:${entry.lastIngestedAt ?? ''}`)
+    .sort();
+  lines.push(`total:${total}`);
+  return createHash('sha1').update(lines.join('\n')).digest('hex').slice(0, 16);
+}
+
+export function readConceptLeaves(rootDir) {
+  const base = join(String(rootDir), 'wiki', 'concepts');
+  const leaves = [];
+  let entries;
+  try {
+    entries = readdirSync(base, { withFileTypes: true, recursive: true });
+  } catch {
+    return leaves;
+  }
+  const toPosix = (value) => value.split(sep).join('/');
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    const parent = entry.parentPath ?? entry.path;
+    if (!parent) continue;
+    const rel = toPosix(relative(base, join(parent, entry.name)));
+    if (!rel || rel.startsWith('..')) continue;
+    const concept = rel.split('/')[0];
+    if (!concept) continue;
+    const head = readFileHead(join(parent, entry.name));
+    const subject = frontmatterSubject(head) ?? entry.name.replace(/\.md$/, '');
+    leaves.push({ path: rel, concept, subject });
+  }
+  return leaves;
+}