@dotdrelle/wiki-manager 0.15.97 → 0.15.99

package/src/orchestrator/knowledgeSignals.test.js

@@ -0,0 +1,193 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  conflictFingerprint,
+  detectConceptConflicts,
+  detectStaleKnowledge,
+  normalizeSubject,
+  readConceptLeaves,
+  readSourceRegistry,
+  readWikiPages,
+  staleFingerprint,
+} from './knowledgeSignals.js';
+
+test('normalizeSubject folds case, accents and punctuation', () => {
+  assert.equal(normalizeSubject('Jedox Cloud'), 'jedox-cloud');
+  assert.equal(normalizeSubject('jedox-cloud'), 'jedox-cloud');
+  assert.equal(normalizeSubject('Souveraineté'), 'souverainete');
+});
+
+test('two homonym leaves under one concept are one conflict, not two', () => {
+  const { conflicts, total } = detectConceptConflicts([
+    { path: 'saas/jedox.md', concept: 'saas', subject: 'Jedox' },
+    { path: 'saas/jedox-cloud.md', concept: 'saas', subject: 'jedox' },
+    { path: 'cout/jedox.md', concept: 'cout', subject: 'Jedox' },
+    { path: 'saas/anaplan.md', concept: 'saas', subject: 'Anaplan' },
+  ]);
+  assert.equal(total, 1);
+  assert.deepEqual(conflicts, [
+    { concept: 'saas', subject: 'jedox', paths: ['saas/jedox-cloud.md', 'saas/jedox.md'] },
+  ]);
+});
+
+test('a conflict in nested sub-folders keeps both distinct paths', () => {
+  const { conflicts, total } = detectConceptConflicts([
+    { path: 'saas/produits/jedox.md', concept: 'saas', subject: 'Jedox' },
+    { path: 'saas/vendors/jedox.md', concept: 'saas', subject: 'Jedox' },
+  ]);
+  assert.equal(total, 1);
+  assert.deepEqual(conflicts[0].paths, ['saas/produits/jedox.md', 'saas/vendors/jedox.md']);
+});
+
+test('the conflict fingerprint is stable and moves past the display ceiling', () => {
+  const a = [{ concept: 'saas', subject: 'jedox', paths: ['saas/b.md', 'saas/a.md'] }];
+  const b = [{ concept: 'saas', subject: 'jedox', paths: ['saas/a.md', 'saas/b.md'] }];
+  assert.equal(conflictFingerprint(a, 1), conflictFingerprint(b, 1));
+  // A 51st conflict beyond the cap must change the version, or it dedups away.
+  assert.notEqual(conflictFingerprint(a, 50), conflictFingerprint(a, 51));
+});
+
+test('the ceiling reports what it dropped instead of hiding it', () => {
+  const leaves = Array.from({ length: 60 }, (_, index) => [
+    { path: `c/s${index}-a.md`, concept: 'c', subject: `s${index}` },
+    { path: `c/s${index}-b.md`, concept: 'c', subject: `s${index}` },
+  ]).flat();
+  const { conflicts, total, dropped } = detectConceptConflicts(leaves);
+  assert.equal(conflicts.length, 50);
+  assert.equal(total, 60);
+  assert.equal(dropped, 10);
+});
+
+test('readConceptLeaves takes the folder as the concept and the frontmatter as the subject', () => {
+  const root = mkdtempSync(join(tmpdir(), 'signals-'));
+  try {
+    mkdirSync(join(root, 'wiki', 'concepts', 'saas', 'produits'), { recursive: true });
+    mkdirSync(join(root, 'wiki', 'concepts', 'saas', 'vendors'), { recursive: true });
+    mkdirSync(join(root, 'wiki', 'concepts', 'cout'), { recursive: true });
+    writeFileSync(join(root, 'wiki', 'concepts', 'saas', 'produits', 'jedox.md'), '---\nsubject: Jedox\n---\nbody');
+    writeFileSync(join(root, 'wiki', 'concepts', 'saas', 'vendors', 'jedox.md'), '---\nsubject: Jedox\n---\nbody');
+    writeFileSync(join(root, 'wiki', 'concepts', 'cout', 'jedox.md'), 'no frontmatter\n');
+    writeFileSync(join(root, 'wiki', 'concepts', 'README.txt'), 'ignore me');
+
+    const leaves = readConceptLeaves(root);
+    assert.deepEqual(
+      leaves.map((leaf) => leaf.path).sort(),
+      ['cout/jedox.md', 'saas/produits/jedox.md', 'saas/vendors/jedox.md'],
+    );
+    const { conflicts, total } = detectConceptConflicts(leaves);
+    assert.equal(total, 1);
+    assert.equal(conflicts[0].concept, 'saas');
+    assert.deepEqual(conflicts[0].paths, ['saas/produits/jedox.md', 'saas/vendors/jedox.md']);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('a corpus without homonyms produces no signal', () => {
+  assert.equal(
+    detectConceptConflicts([
+      { path: 'saas/a.md', concept: 'saas', subject: 'A' },
+      { path: 'saas/b.md', concept: 'saas', subject: 'B' },
+    ]).total,
+    0,
+  );
+  assert.equal(detectConceptConflicts([]).total, 0);
+});
+
+test('stale knowledge is aged sources plus registry paths that no longer exist', () => {
+  const now = Date.parse('2026-06-01T00:00:00.000Z');
+  const recent = '2026-05-30T00:00:00.000Z';
+  const registry = {
+    sources: [
+      { sourceId: 'a', archivePath: 'raw/ingested/a.md', status: 'active', lastIngestedAt: recent, producedPages: ['wiki/concepts/saas/a.md'] },
+      { sourceId: 'b', archivePath: 'raw/ingested/b.md', status: 'active', lastIngestedAt: recent, producedPages: [] },
+      { sourceId: 'e', archivePath: 'raw/ingested/e.md', status: 'active', lastIngestedAt: recent, producedPages: ['wiki/concepts/saas/e-gone.md'] },
+      { sourceId: 'f', archivePath: 'raw/ingested/f.md', status: 'active', lastIngestedAt: '2025-01-01T00:00:00.000Z', producedPages: [] },
+      { sourceId: 'g', archivePath: 'raw/ingested/g.md', status: 'retracted', lastIngestedAt: '2024-01-01T00:00:00.000Z', producedPages: [] },
+      { sourceId: 'h', archivePath: 'raw/ingested/h.md', status: 'active', lastIngestedAt: null, producedPages: [] },
+    ],
+  };
+  // Only b's archive and e's produced page are gone.
+  const exists = (path) => !path.includes('raw/ingested/b.md') && !path.endsWith('e-gone.md');
+
+  const { stale, total, dropped, counts } = detectStaleKnowledge(registry, {
+    rootDir: '/ws', now, staleAfterDays: 180, exists,
+  });
+  assert.equal(total, 3, 'a recent, a retracted and a never-ingested source are not stale');
+  assert.equal(dropped, 0);
+  assert.deepEqual(counts, { aged: 1, vanishedArchive: 1, vanishedPage: 1, orphan: 0 });
+  assert.deepEqual(stale.map((entry) => entry.kind), ['aged', 'vanished-archive', 'vanished-page']);
+  assert.equal(stale.find((entry) => entry.kind === 'aged').sourceId, 'f');
+  assert.equal(stale.find((entry) => entry.kind === 'vanished-archive').path, 'raw/ingested/b.md');
+  assert.equal(stale.find((entry) => entry.kind === 'vanished-page').path, 'wiki/concepts/saas/e-gone.md');
+});
+
+test('the stale fingerprint is stable and counts the whole set', () => {
+  const a = [{ kind: 'aged', sourceId: 'b', path: 'raw/ingested/b.md', lastIngestedAt: '2025-01-01T00:00:00.000Z' }];
+  assert.equal(staleFingerprint(a, 1), staleFingerprint(a, 1));
+  assert.notEqual(staleFingerprint(a, 1), staleFingerprint(a, 2));
+});
+
+test('readSourceRegistry tolerates an absent or corrupt file', () => {
+  const root = mkdtempSync(join(tmpdir(), 'registry-'));
+  try {
+    assert.deepEqual(readSourceRegistry(root), { sources: [] });
+    mkdirSync(join(root, '.wiki'), { recursive: true });
+    writeFileSync(join(root, '.wiki', 'source-registry.json'), '{not json');
+    assert.deepEqual(readSourceRegistry(root), { sources: [] });
+    writeFileSync(
+      join(root, '.wiki', 'source-registry.json'),
+      JSON.stringify({ version: 1, sources: [{ sourceId: 'a' }] }),
+    );
+    assert.equal(readSourceRegistry(root).sources.length, 1);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('a wiki page no active source backs is an orphan fact', () => {
+  const now = Date.parse('2026-06-01T00:00:00.000Z');
+  const recent = '2026-05-30T00:00:00.000Z';
+  const registry = {
+    sources: [
+      { sourceId: 'a', archivePath: 'raw/ingested/a.md', status: 'active', lastIngestedAt: recent, producedPages: ['wiki/concepts/saas/a.md'] },
+      { sourceId: 'b', archivePath: 'raw/ingested/b.md', status: 'retracted', lastIngestedAt: recent, producedPages: ['wiki/concepts/saas/retracted.md'] },
+    ],
+  };
+  const { stale, counts } = detectStaleKnowledge(registry, {
+    rootDir: '/ws',
+    now,
+    staleAfterDays: 180,
+    exists: () => true,
+    wikiPages: ['wiki/concepts/saas/a.md', 'wiki/concepts/saas/handwritten.md', 'wiki/concepts/saas/retracted.md'],
+  });
+  // A page backed by an ACTIVE source is not an orphan; a hand-written one and
+  // one produced by a RETRACTED source are.
+  assert.deepEqual(
+    stale.filter((entry) => entry.kind === 'orphan').map((entry) => entry.path),
+    ['wiki/concepts/saas/handwritten.md', 'wiki/concepts/saas/retracted.md'],
+  );
+  assert.equal(counts.orphan, 2);
+
+  // Without the inventory, no orphan kind is invented.
+  const without = detectStaleKnowledge(registry, { rootDir: '/ws', now, exists: () => true });
+  assert.equal(without.stale.some((entry) => entry.kind === 'orphan'), false);
+});
+
+test('readWikiPages inventories wiki/**/*.md, names only', () => {
+  const root = mkdtempSync(join(tmpdir(), 'wikipages-'));
+  try {
+    mkdirSync(join(root, 'wiki', 'concepts', 'saas'), { recursive: true });
+    mkdirSync(join(root, 'wiki', 'answers'), { recursive: true });
+    writeFileSync(join(root, 'wiki', 'concepts', 'saas', 'a.md'), 'x');
+    writeFileSync(join(root, 'wiki', 'answers', 'b.md'), 'x');
+    writeFileSync(join(root, 'wiki', 'notes.txt'), 'x');
+    assert.deepEqual(readWikiPages(root), ['wiki/answers/b.md', 'wiki/concepts/saas/a.md']);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/src/orchestrator/proactiveReviewScheduler.js

@@ -0,0 +1,240 @@
+/*
+ Proactive reviews: the manager noticing, from a fact it already computed, that
+ a workspace is worth auditing — and PROPOSING one, never mutating anything.
+
+ This module is the deterministic decision only: which task completion is a
+ trigger, whether the workspace's opt-in config allows one, and the dedup /
+ cooldown / budget arithmetic. Enqueueing the run and persisting the resulting
+ note belong to the runtime; keeping the decision pure is what makes it
+ testable without a session, a queue or a model.
+*/
+
+// Read-only, no worktree: the review capability the gateway already declares.
+export const PROACTIVE_REVIEW_CAPABILITY = 'agent.review';
+
+export const PROACTIVE_DEFAULTS = {
+  enabled: false,
+  triggers: [
+    'knowledge.ingested',
+    'knowledge.rebuilt',
+    'knowledge.stale',
+    'knowledge.conflict_detected',
+  ],
+  cooldownMs: 6 * 60 * 60 * 1000,
+  runsPerDay: 4,
+  concurrency: 1,
+  staleAfterDays: 180,
+};
+
+/**
+ * Which task completion is a trigger. Derived from the capability/operation
+ * the production agent actually exposes — never a registered list an agent
+ * could silently stop matching.
+ */
+export function triggerForTask({ capability, operation } = {}) {
+  const cap = String(capability ?? '').trim();
+  const op = String(operation ?? '').trim();
+  // `ingest_plan` is a dry-run under `knowledge.update` (read lock, writes only
+  // `.wiki/ingest-plans/`): the corpus has not moved, so it must be excluded
+  // BEFORE the capability check that would otherwise accept it.
+  if (op === 'ingest_plan') return null;
+  if (cap === 'knowledge.rebuild' || op === 'ingest_rebuild') return 'knowledge.rebuilt';
+  if (
+    cap === 'knowledge.update'
+    || cap === 'knowledge.pipeline' // the default one-shot path: it ingests too
+    || op === 'ingest'
+    || op === 'ingest_apply'
+    || op === 'pipeline'
+  ) {
+    return 'knowledge.ingested';
+  }
+  return null;
+}
+
+const EVIDENCE_CHARS = 600;
+
+// The detector's exact facts, named for the agent. A fingerprint alone makes it
+// re-read the whole wiki to rediscover what the deterministic scan already
+// established — and a vanished page is an ABSENCE, which cannot be rediscovered
+// by reading. Bounded: the objective is a briefing, not a dump.
+function evidenceDetail(evidence) {
+  if (!evidence || typeof evidence !== 'object') return '';
+  const items = Array.isArray(evidence.items) ? evidence.items : [];
+  const listed = evidence.kind === 'conflict'
+    ? items.slice(0, 5).map((item) => `${item.concept}/${item.subject} (${(item.paths ?? []).join(', ')})`)
+    : items.slice(0, 5).map((item) => `${item.kind}: ${item.path}`);
+  const more = items.length > 5 ? '; …' : '';
+  if (evidence.kind === 'conflict') {
+    return `${items.length} homonym leaf group(s): ${listed.join('; ')}${more}`;
+  }
+  if (evidence.kind === 'stale') {
+    const counts = evidence.counts ?? {};
+    const parts = [
+      counts.aged ? `${counts.aged} aged source(s)` : null,
+      counts.vanishedArchive ? `${counts.vanishedArchive} vanished archive(s)` : null,
+      counts.vanishedPage ? `${counts.vanishedPage} vanished page(s)` : null,
+    ].filter(Boolean).join(', ');
+    return `${parts}${listed.length ? ` — ${listed.join('; ')}` : ''}${more}`;
+  }
+  return '';
+}
+
+/**
+ * The objective a proactive review runs under. Routing is EXPLICIT (a
+ * `capabilityPlan` naming `agent.review`), so the evidence below may name any
+ * path without risking the alias resolver — the reviewer is told WHAT the scan
+ * found, not a fingerprint to re-derive it from.
+ */
+export function buildProactiveReviewObjective({ trigger, sourceVersion, evidence = null } = {}) {
+  const version = sourceVersion ? ` (source ${sourceVersion})` : '';
+  const fact = String(trigger ?? 'a knowledge change');
+  const detail = evidenceDetail(evidence).slice(0, EVIDENCE_CHARS);
+  return [
+    `audit the workspace: ${fact}${version} just landed.`,
+    detail ? `The deterministic scan already found: ${detail}.` : '',
+    'Read the wiki and describe the gaps — no changes, no worktree.',
+  ].filter(Boolean).join(' ');
+}
+
+/**
+ * The workspace's opt-in block (`proactiveReviews` in `.wikirc.yaml`). Missing
+ * or malformed means DISABLED: a typo must never turn on spend the operator
+ * did not ask for.
+ */
+export function normalizeProactiveConfig(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return { ...PROACTIVE_DEFAULTS, triggers: [...PROACTIVE_DEFAULTS.triggers] };
+  }
+  const positive = (raw, fallback) => {
+    const number = Number(raw);
+    return Number.isFinite(number) && number >= 0 ? number : fallback;
+  };
+  const triggers = Array.isArray(value.triggers)
+    ? value.triggers.map((trigger) => String(trigger).trim()).filter(Boolean)
+    : [...PROACTIVE_DEFAULTS.triggers];
+  return {
+    enabled: value.enabled === true,
+    triggers,
+    cooldownMs: positive(value.cooldownMs, PROACTIVE_DEFAULTS.cooldownMs),
+    runsPerDay: positive(value?.budget?.runsPerDay, PROACTIVE_DEFAULTS.runsPerDay),
+    concurrency: Math.max(1, positive(value.concurrency, PROACTIVE_DEFAULTS.concurrency)),
+    // How old a source's last ingest must be before `knowledge.stale` fires.
+    staleAfterDays: positive(value.staleAfterDays, PROACTIVE_DEFAULTS.staleAfterDays),
+  };
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function workspaceState(state, workspace) {
+  const key = String(workspace ?? '');
+  let entry = state.get(key);
+  if (!entry) {
+    entry = { lastFiredAt: null, seen: new Set(), dayStartedAt: null, dayCount: 0, inFlight: 0 };
+    state.set(key, entry);
+  }
+  return entry;
+}
+
+export function createProactiveReviewScheduler({ now = () => Date.now(), db = null, pendingReviews = null } = {}) {
+  // Durable spend and dedup belong beside the runtime queue, in its SQLite DB.
+  // Slots are reconciled with the persisted control queue before each decision.
+  db?.exec('CREATE TABLE IF NOT EXISTS proactive_review_state (workspace TEXT PRIMARY KEY, payload TEXT NOT NULL)');
+  const save = db?.prepare('INSERT INTO proactive_review_state (workspace, payload) VALUES (?, ?) ON CONFLICT(workspace) DO UPDATE SET payload = excluded.payload');
+  const state = new Map((db?.prepare('SELECT workspace, payload FROM proactive_review_state').all() ?? []).map((row) => {
+    const entry = JSON.parse(row.payload);
+    return [row.workspace, { ...entry, seen: new Set(entry.seen), inFlight: 0, inFlightTrigger: null }];
+  }));
+  function persist(workspace, entry) {
+    save?.run(String(workspace ?? ''), JSON.stringify({ ...entry, seen: [...entry.seen] }));
+  }
+
+  function decide({ workspace, trigger, sourceVersion = null, config = null } = {}) {
+    const cfg = normalizeProactiveConfig(config);
+    const skip = (reason) => ({ action: 'skip', reason, config: cfg });
+    if (!cfg.enabled) return skip('disabled');
+    if (!cfg.triggers.includes(String(trigger ?? ''))) return skip('trigger_disabled');
+    if (pendingReviews) {
+      for (const item of state.values()) { item.inFlight = 0; item.inFlightTrigger = null; }
+      for (const review of pendingReviews()) {
+        const pending = workspaceState(state, review.workspace);
+        pending.inFlight += 1;
+        pending.inFlightTrigger = review.trigger;
+      }
+    }
+    const entry = workspaceState(state, workspace);
+    const at = now();
+    // The daily window is what bounds `seen`: pruning it at rollover keeps
+    // dedup per-day without an ever-growing Set in a long-lived process (the
+    // same family as MAX_SESSION_EVENTS and run.events).
+    if (entry.dayStartedAt == null || at - entry.dayStartedAt >= DAY_MS) {
+      entry.dayStartedAt = at;
+      entry.dayCount = 0;
+      entry.seen.clear();
+    }
+    // The same source version is the same review: a second task of one ingest
+    // run must not queue a second audit.
+    if (sourceVersion != null && entry.seen.has(String(sourceVersion))) return skip('duplicate');
+    if (entry.inFlight >= cfg.concurrency) return skip('concurrency');
+    if (entry.lastFiredAt != null && at - entry.lastFiredAt < cfg.cooldownMs) return skip('cooldown');
+    if (entry.dayCount >= cfg.runsPerDay) return skip('budget');
+    // Each workspace can tighten its own limit, but cannot exceed the global
+    // default by opening another workspace.
+    const globalInFlight = [...state.values()].reduce((sum, item) => sum + item.inFlight, 0);
+    if (globalInFlight >= PROACTIVE_DEFAULTS.concurrency) return skip('concurrency');
+
+    if (sourceVersion != null) entry.seen.add(String(sourceVersion));
+    entry.lastFiredAt = at;
+    entry.dayCount += 1;
+    entry.inFlight += 1;
+    // What is holding the slot, so a later skip can SAY another review took
+    // precedence instead of a bare "concurrency".
+    entry.inFlightTrigger = String(trigger ?? '');
+    persist(workspace, entry);
+    return {
+      action: 'review',
+      config: cfg,
+      capability: PROACTIVE_REVIEW_CAPABILITY,
+      workspace: String(workspace ?? ''),
+      trigger: String(trigger ?? ''),
+      sourceVersion: sourceVersion == null ? null : String(sourceVersion),
+    };
+  }
+
+  // Called when the review run reaches a terminal state (success, failure or
+  // cancellation), so the concurrency slot is never leaked. `undo` is for the
+  // failure path where the review was never actually queued: it returns the
+  // budget unit and releases the version, instead of burning an audit that
+  // will never happen. Never allocates state for an unknown workspace.
+  function release(workspace, { undo = false, sourceVersion = null } = {}) {
+    const entry = state.get(String(workspace ?? ''));
+    if (!entry) return;
+    if (entry.inFlight > 0) entry.inFlight -= 1;
+    if (entry.inFlight <= 0) entry.inFlightTrigger = null;
+    if (undo) {
+      if (entry.dayCount > 0) entry.dayCount -= 1;
+      if (sourceVersion != null) entry.seen.delete(String(sourceVersion));
+    }
+    persist(workspace, entry);
+  }
+
+  // Display-only: what the budget panel reads. A read must not allocate.
+  function snapshot(workspace) {
+    const entry = state.get(String(workspace ?? ''));
+    if (!entry) return { lastFiredAt: null, runsToday: 0, inFlight: 0, inFlightTrigger: null, seenVersions: 0 };
+    return {
+      lastFiredAt: entry.lastFiredAt,
+      runsToday: entry.dayCount,
+      inFlight: entry.inFlight,
+      inFlightTrigger: entry.inFlightTrigger ?? null,
+      seenVersions: entry.seen.size,
+    };
+  }
+
+  // How many workspaces carry scheduler state — a cheap diagnostic, and the
+  // proof that a display read never allocates.
+  function workspaceCount() {
+    return state.size;
+  }
+
+  return { decide, release, snapshot, workspaceCount };
+}

package/src/orchestrator/proactiveReviewScheduler.test.js

@@ -0,0 +1,243 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { DatabaseSync } from 'node:sqlite';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  PROACTIVE_DEFAULTS,
+  buildProactiveReviewObjective,
+  createProactiveReviewScheduler,
+  normalizeProactiveConfig,
+  triggerForTask,
+} from './proactiveReviewScheduler.js';
+
+test('triggerForTask derives the two knowledge facts from the real capabilities', () => {
+  assert.equal(triggerForTask({ capability: 'knowledge.update', operation: 'ingest_apply' }), 'knowledge.ingested');
+  assert.equal(triggerForTask({ operation: 'ingest' }), 'knowledge.ingested');
+  assert.equal(triggerForTask({ capability: 'knowledge.rebuild', operation: 'run' }), 'knowledge.rebuilt');
+  assert.equal(triggerForTask({ operation: 'ingest_rebuild' }), 'knowledge.rebuilt');
+  assert.equal(triggerForTask({ capability: 'knowledge.pipeline', operation: 'pipeline' }), 'knowledge.ingested');
+  // A dry-run takes a read lock and writes only .wiki/ingest-plans/: the corpus
+  // has not moved, so there is nothing new to audit.
+  assert.equal(triggerForTask({ capability: 'knowledge.update', operation: 'ingest_plan' }), null);
+  assert.equal(triggerForTask({ operation: 'ingest_plan' }), null);
+  assert.equal(triggerForTask({ capability: 'document.build', operation: 'build' }), null);
+  assert.equal(triggerForTask({ capability: 'knowledge.check', operation: 'lint' }), null);
+  assert.equal(triggerForTask({}), null);
+});
+
+test('normalizeProactiveConfig stays disabled on anything malformed', () => {
+  assert.equal(normalizeProactiveConfig(undefined).enabled, false);
+  assert.equal(normalizeProactiveConfig('yes').enabled, false);
+  assert.equal(normalizeProactiveConfig({ enabled: 'true' }).enabled, false, 'only a real boolean opts in');
+  const config = normalizeProactiveConfig({ enabled: true, cooldownMs: -5, budget: { runsPerDay: 2 } });
+  assert.equal(config.enabled, true);
+  assert.equal(config.cooldownMs, PROACTIVE_DEFAULTS.cooldownMs, 'a negative cooldown falls back');
+  assert.equal(config.runsPerDay, 2);
+  assert.equal(config.staleAfterDays, PROACTIVE_DEFAULTS.staleAfterDays);
+  assert.equal(normalizeProactiveConfig({ enabled: true, staleAfterDays: 30 }).staleAfterDays, 30);
+});
+
+test('the same source version never queues a second audit', () => {
+  const scheduler = createProactiveReviewScheduler();
+  // concurrency 2 so the second decision reaches the cooldown, not the slot.
+  const config = { enabled: true, concurrency: 2 };
+  assert.equal(
+    scheduler.decide({ workspace: 'docs', trigger: 'knowledge.ingested', sourceVersion: 'v1', config }).action,
+    'review',
+  );
+  const again = scheduler.decide({ workspace: 'docs', trigger: 'knowledge.ingested', sourceVersion: 'v1', config });
+  assert.equal(again.action, 'skip');
+  assert.equal(again.reason, 'duplicate');
+  const other = scheduler.decide({ workspace: 'docs', trigger: 'knowledge.ingested', sourceVersion: 'v2', config });
+  assert.equal(other.reason, 'cooldown', 'a different version still waits for the cooldown');
+});
+
+test('cooldown and budget bound the spend per workspace', () => {
+  let clock = 1_000_000;
+  const scheduler = createProactiveReviewScheduler({ now: () => clock });
+  const config = { enabled: true, cooldownMs: 100, budget: { runsPerDay: 2 }, concurrency: 2 };
+  assert.equal(
+    scheduler.decide({ workspace: 'w', trigger: 'knowledge.ingested', sourceVersion: 'a', config }).action,
+    'review',
+  );
+  assert.equal(
+    scheduler.decide({ workspace: 'w', trigger: 'knowledge.rebuilt', sourceVersion: 'b', config }).reason,
+    'cooldown',
+  );
+  scheduler.release('w');
+  clock += 1_000;
+  assert.equal(
+    scheduler.decide({ workspace: 'w', trigger: 'knowledge.rebuilt', sourceVersion: 'b', config }).action,
+    'review',
+  );
+  scheduler.release('w');
+  clock += 1_000;
+  assert.equal(
+    scheduler.decide({ workspace: 'w', trigger: 'knowledge.rebuilt', sourceVersion: 'c', config }).reason,
+    'budget',
+  );
+});
+
+test('one in-flight review holds the concurrency slot until it is released', () => {
+  const scheduler = createProactiveReviewScheduler();
+  const config = { enabled: true, cooldownMs: 0, budget: { runsPerDay: 10 }, concurrency: 1 };
+  assert.equal(
+    scheduler.decide({ workspace: 'w', trigger: 'knowledge.ingested', sourceVersion: 'a', config }).action,
+    'review',
+  );
+  assert.equal(
+    scheduler.decide({ workspace: 'w', trigger: 'knowledge.ingested', sourceVersion: 'b', config }).reason,
+    'concurrency',
+  );
+  scheduler.release('w');
+  assert.equal(
+    scheduler.decide({ workspace: 'w', trigger: 'knowledge.ingested', sourceVersion: 'b', config }).action,
+    'review',
+  );
+});
+
+test('disabled or untriggered facts never start anything', () => {
+  const scheduler = createProactiveReviewScheduler();
+  assert.equal(scheduler.decide({ workspace: 'w', trigger: 'knowledge.ingested', config: null }).reason, 'disabled');
+  assert.equal(
+    scheduler.decide({ workspace: 'w', trigger: 'knowledge.rebuilt', config: { enabled: false } }).reason,
+    'disabled',
+  );
+  assert.equal(
+    scheduler.decide({
+      workspace: 'w',
+      trigger: 'knowledge.rebuilt',
+      config: { enabled: true, triggers: ['knowledge.ingested'] },
+    }).reason,
+    'trigger_disabled',
+  );
+});
+
+test('the proactive objective names the evidence the scan already found', () => {
+  const objective = buildProactiveReviewObjective({
+    trigger: 'knowledge.stale',
+    sourceVersion: 'sha-9',
+    evidence: {
+      kind: 'stale',
+      counts: { aged: 1, vanishedArchive: 1, vanishedPage: 57 },
+      items: [
+        { kind: 'aged', path: 'raw/ingested/a.md' },
+        { kind: 'vanished-page', path: 'wiki/concepts/saas/gone.md' },
+      ],
+    },
+  });
+  assert.match(objective, /audit the workspace/);
+  assert.match(objective, /knowledge\.stale/);
+  assert.match(objective, /sha-9/);
+  assert.match(objective, /1 aged source\(s\)/);
+  assert.match(objective, /1 vanished archive\(s\)/);
+  assert.match(objective, /57 vanished page\(s\)/);
+  assert.match(objective, /raw\/ingested\/a\.md/);
+  assert.match(objective, /wiki\/concepts\/saas\/gone\.md/);
+  // Routing is explicit (capabilityPlan), so an evidence path may contain any
+  // word — the alias resolver is no longer on the path.
+  const noEvidence = buildProactiveReviewObjective({ trigger: 'knowledge.ingested', sourceVersion: 'v1' });
+  assert.match(noEvidence, /audit the workspace/);
+  assert.doesNotMatch(noEvidence, /deterministic scan/);
+});
+
+test('reading the budget, or releasing an unknown workspace, never allocates', () => {
+  const scheduler = createProactiveReviewScheduler();
+  assert.deepEqual(scheduler.snapshot('never-seen'), {
+    lastFiredAt: null, runsToday: 0, inFlight: 0, inFlightTrigger: null, seenVersions: 0,
+  });
+  scheduler.release('never-seen');
+  scheduler.release('never-seen', { undo: true });
+  assert.equal(scheduler.workspaceCount(), 0);
+});
+
+test('the seen set is pruned with the daily window, not grown forever', () => {
+  let clock = 1_000_000;
+  const scheduler = createProactiveReviewScheduler({ now: () => clock });
+  const config = { enabled: true, cooldownMs: 0, budget: { runsPerDay: 10 }, concurrency: 5 };
+  assert.equal(
+    scheduler.decide({ workspace: 'w', trigger: 'knowledge.ingested', sourceVersion: 'v1', config }).action,
+    'review',
+  );
+  assert.equal(
+    scheduler.decide({ workspace: 'w', trigger: 'knowledge.ingested', sourceVersion: 'v1', config }).reason,
+    'duplicate',
+  );
+  // The window rolls: dedup starts clean rather than holding every version ever.
+  scheduler.release('w');
+  clock += 24 * 60 * 60 * 1000;
+  assert.equal(
+    scheduler.decide({ workspace: 'w', trigger: 'knowledge.ingested', sourceVersion: 'v1', config }).action,
+    'review',
+  );
+});
+
+test('an undone reservation returns the budget unit and the version', () => {
+  const scheduler = createProactiveReviewScheduler();
+  const config = { enabled: true, cooldownMs: 0, budget: { runsPerDay: 1 }, concurrency: 1 };
+  assert.equal(
+    scheduler.decide({ workspace: 'w', trigger: 'knowledge.ingested', sourceVersion: 'v1', config }).action,
+    'review',
+  );
+  scheduler.release('w', { undo: true, sourceVersion: 'v1' });
+  // Neither the budget nor the version was consumed: the audit can still happen.
+  const again = scheduler.decide({ workspace: 'w', trigger: 'knowledge.ingested', sourceVersion: 'v1', config });
+  assert.equal(again.action, 'review');
+});
+
+test('the in-flight review names itself, so a skip can say who holds the slot', () => {
+  const scheduler = createProactiveReviewScheduler();
+  const config = { enabled: true, cooldownMs: 0, budget: { runsPerDay: 10 }, concurrency: 1 };
+  scheduler.decide({ workspace: 'w', trigger: 'knowledge.conflict_detected', sourceVersion: 'f1', config });
+  assert.equal(scheduler.snapshot('w').inFlightTrigger, 'knowledge.conflict_detected');
+  scheduler.release('w');
+  assert.equal(scheduler.snapshot('w').inFlightTrigger, null);
+});
+
+
+test('restart preserves dedup, cooldown and daily spend in SQLite', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'proactive-restart-'));
+  const path = join(dir, 'runtime.db');
+  let db = new DatabaseSync(path);
+  try {
+    let clock = 1000;
+    const make = () => createProactiveReviewScheduler({ db, now: () => clock });
+    const request = { workspace: 'w', trigger: 'knowledge.ingested', sourceVersion: 'v1',
+      config: { enabled: true, cooldownMs: 100, budget: { runsPerDay: 1 } } };
+    const first = make();
+    assert.equal(first.decide(request).action, 'review');
+    first.release('w');
+    db.close();
+    db = new DatabaseSync(path);
+    const restarted = make();
+    assert.equal(restarted.decide(request).reason, 'duplicate');
+    assert.equal(restarted.decide({ ...request, sourceVersion: 'v2' }).reason, 'cooldown');
+    clock += 101;
+    assert.equal(restarted.decide({ ...request, sourceVersion: 'v2' }).reason, 'budget');
+    clock += 24 * 60 * 60 * 1000;
+    assert.equal(restarted.decide({ ...request, sourceVersion: 'v2' }).action, 'review');
+  } finally { db.close(); rmSync(dir, { recursive: true, force: true }); }
+});
+
+test('the global slot is shared across workspaces and returned on completion', () => {
+  const scheduler = createProactiveReviewScheduler();
+  const request = { trigger: 'knowledge.ingested', sourceVersion: 'v1',
+    config: { enabled: true, cooldownMs: 0, concurrency: 5 } };
+  assert.equal(scheduler.decide({ ...request, workspace: 'a' }).action, 'review');
+  assert.equal(scheduler.decide({ ...request, workspace: 'b' }).reason, 'concurrency');
+  scheduler.release('a');
+  assert.equal(scheduler.decide({ ...request, workspace: 'b' }).action, 'review');
+});
+
+
+test('recovered and queued reviews hold the global slot until terminal or cancelled', () => {
+  let pending = [{ workspace: 'old', trigger: 'knowledge.stale' }];
+  const scheduler = createProactiveReviewScheduler({ pendingReviews: () => pending });
+  const request = { workspace: 'new', trigger: 'knowledge.ingested', config: { enabled: true } };
+  assert.equal(scheduler.decide(request).reason, 'concurrency');
+  pending = [];
+  assert.equal(scheduler.decide(request).action, 'review');
+});