@sanqianx/project-knowledge 5.0.24 → 5.0.26

package/_site/scripts/vendor-modules.js

@@ -1,49 +1,49 @@
-'use strict';
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-const { execFileSync } = require('node:child_process');
-const AtomicFile = require('../lib/atomic-file');
-
-const root = path.resolve(__dirname, '../..');
-const destination = path.join(root, '_modules', 'knowledge-engine');
-const manifestFile = path.join(root, 'vendor-manifest.json');
-const hash = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
-function sources(source) {
-  const files = ['package.json', 'README.md', 'ui/index.html', 'ui/app.js', 'ui/app.css'];
-  function walk(directory) {
-    for (const entry of fs.readdirSync(path.join(source, directory), { withFileTypes: true })) {
-      if (entry.isSymbolicLink()) throw new Error('Symlinks are not accepted in a vendored runtime');
-      const relative = `${directory}/${entry.name}`;
-      if (entry.isDirectory()) walk(relative); else if (entry.isFile()) files.push(relative);
-    }
-  }
-  walk('src'); return files.sort();
-}
-function vendor(source) {
-  source = path.resolve(source);
-  const pkg = JSON.parse(fs.readFileSync(path.join(source, 'package.json')));
-  if (pkg.name !== '@sanqianx/ai-coding-knowledge-engine' || Object.keys(pkg.dependencies || {}).length || Object.keys(pkg.devDependencies || {}).length) throw new Error('The engine must remain a dependency-free runtime');
-  const previous = fs.existsSync(manifestFile) ? JSON.parse(fs.readFileSync(manifestFile)) : { schema: 'project-knowledge/vendor-runtime/v1', modules: {} };
-  const priorFiles = previous.modules['knowledge-engine']?.files || {};
-  const files = {};
-  for (const relative of sources(source)) {
-    const sourceFile = path.join(source, relative), target = path.join(destination, relative);
-    if (fs.lstatSync(sourceFile).isSymbolicLink() || fs.existsSync(target) && fs.lstatSync(target).isSymbolicLink()) throw new Error('Unsafe runtime path');
-    const bytes = fs.readFileSync(sourceFile), digest = hash(bytes);
-    if (fs.existsSync(target)) {
-      const current = hash(fs.readFileSync(target));
-      if (current !== digest && current !== priorFiles[relative]) throw new Error(`Preserving unrecognized local runtime change: ${relative}`);
-    }
-    AtomicFile.writeFileAtomic(target, bytes); files[relative] = digest;
-  }
-  // No broad cleanup: obsolete files remain visible to the verifier until an
-  // explicit reviewed cleanup. Untracked/user changes are never overwritten.
-  previous.modules['knowledge-engine'] = { name: pkg.name, version: pkg.version, root: '_modules/knowledge-engine', files };
-  if (fs.existsSync(path.join(source, '.git'))) previous.modules['knowledge-engine'].sourceCommit = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: source, encoding: 'utf8', windowsHide: true }).trim();
-  AtomicFile.writeJsonAtomic(manifestFile, previous);
-  process.stdout.write(`Vendored knowledge-engine ${pkg.version}: ${Object.keys(files).length} runtime files\n`);
-}
-const option = process.argv.indexOf('--engine-source');
-if (option < 0 || !process.argv[option + 1]) { process.stderr.write('Usage: vendor-modules --engine-source <explicit checkout path>\n'); process.exitCode = 1; }
-else vendor(process.argv[option + 1]);
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync } = require('node:child_process');
+const AtomicFile = require('../lib/atomic-file');
+
+const root = path.resolve(__dirname, '../..');
+const destination = path.join(root, '_modules', 'knowledge-engine');
+const manifestFile = path.join(root, 'vendor-manifest.json');
+const hash = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+function sources(source) {
+  const files = ['package.json', 'README.md', 'ui/index.html', 'ui/app.js', 'ui/app.css'];
+  function walk(directory) {
+    for (const entry of fs.readdirSync(path.join(source, directory), { withFileTypes: true })) {
+      if (entry.isSymbolicLink()) throw new Error('Symlinks are not accepted in a vendored runtime');
+      const relative = `${directory}/${entry.name}`;
+      if (entry.isDirectory()) walk(relative); else if (entry.isFile()) files.push(relative);
+    }
+  }
+  walk('src'); return files.sort();
+}
+function vendor(source) {
+  source = path.resolve(source);
+  const pkg = JSON.parse(fs.readFileSync(path.join(source, 'package.json')));
+  if (pkg.name !== '@sanqianx/ai-coding-knowledge-engine' || Object.keys(pkg.dependencies || {}).length || Object.keys(pkg.devDependencies || {}).length) throw new Error('The engine must remain a dependency-free runtime');
+  const previous = fs.existsSync(manifestFile) ? JSON.parse(fs.readFileSync(manifestFile)) : { schema: 'project-knowledge/vendor-runtime/v1', modules: {} };
+  const priorFiles = previous.modules['knowledge-engine']?.files || {};
+  const files = {};
+  for (const relative of sources(source)) {
+    const sourceFile = path.join(source, relative), target = path.join(destination, relative);
+    if (fs.lstatSync(sourceFile).isSymbolicLink() || fs.existsSync(target) && fs.lstatSync(target).isSymbolicLink()) throw new Error('Unsafe runtime path');
+    const bytes = fs.readFileSync(sourceFile), digest = hash(bytes);
+    if (fs.existsSync(target)) {
+      const current = hash(fs.readFileSync(target));
+      if (current !== digest && current !== priorFiles[relative]) throw new Error(`Preserving unrecognized local runtime change: ${relative}`);
+    }
+    AtomicFile.writeFileAtomic(target, bytes); files[relative] = digest;
+  }
+  // No broad cleanup: obsolete files remain visible to the verifier until an
+  // explicit reviewed cleanup. Untracked/user changes are never overwritten.
+  previous.modules['knowledge-engine'] = { name: pkg.name, version: pkg.version, root: '_modules/knowledge-engine', files };
+  if (fs.existsSync(path.join(source, '.git'))) previous.modules['knowledge-engine'].sourceCommit = execFileSync('git', ['rev-parse', 'HEAD'], { cwd: source, encoding: 'utf8', windowsHide: true }).trim();
+  AtomicFile.writeJsonAtomic(manifestFile, previous);
+  process.stdout.write(`Vendored knowledge-engine ${pkg.version}: ${Object.keys(files).length} runtime files\n`);
+}
+const option = process.argv.indexOf('--engine-source');
+if (option < 0 || !process.argv[option + 1]) { process.stderr.write('Usage: vendor-modules --engine-source <explicit checkout path>\n'); process.exitCode = 1; }
+else vendor(process.argv[option + 1]);

package/_site/scripts/verify-module-runtime.js

@@ -1,50 +1,50 @@
-'use strict';
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-const { spawnSync } = require('child_process');
-const root = path.resolve(__dirname, '../..');
-const workingTree = process.argv.includes('--working-tree');
-function isPinnedModuleVersion(name, value) {
-  const version = name === 'claude-ai-workbench' ? String(value || '').replace(/^npm:@sanqianx\/claude-ai-workbench@/, '') : value;
-  return /^\d+\.\d+\.\d+(?:-rc\.\d+)?$/.test(version || '');
-}
-function verify() {
-  const manifest = JSON.parse(fs.readFileSync(path.join(root, 'vendor-manifest.json'), 'utf8'));
-  if (manifest.schema !== 'project-knowledge/vendor-runtime/v1') throw new Error('Invalid runtime manifest');
-  const engine = manifest.modules['knowledge-engine'];
-  if (!engine || engine.root !== '_modules/knowledge-engine') throw new Error('Missing engine runtime');
-  const packageInfo = JSON.parse(fs.readFileSync(path.join(root, 'package.json')));
-  for (const dependency of ['claude-ai-workbench', '@sanqianx/vector-hub', '@sanqianx/ai-coding-event-bridge-console']) {
-    if (!isPinnedModuleVersion(dependency, packageInfo.dependencies[dependency])) throw new Error(`Module dependency must be pinned: ${dependency}`);
-  }
-  const required = ['package.json', 'src/bin.js', 'src/server.js', 'src/coordinator.js', 'src/analysis-worker.js', 'ui/index.html', 'ui/app.js', 'ui/app.css'];
-  if (required.some(file => !engine.files[file])) throw new Error('Incomplete runtime manifest');
-  const hasGit = fs.existsSync(path.join(root, '.git'));
-  function checkTree(directory, prefix = '') {
-    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
-      const relative = prefix + entry.name;
-      if (entry.isSymbolicLink()) throw new Error(`Unsafe runtime path: ${relative}`);
-      if (entry.isDirectory()) checkTree(path.join(directory, entry.name), relative + '/');
-      else if (!Object.hasOwn(engine.files, relative)) throw new Error(`Unreviewed runtime file: ${relative}`);
-    }
-  }
-  checkTree(path.join(root, engine.root));
-  for (const [relative, expected] of Object.entries(engine.files)) {
-    if (relative.includes('..') || path.isAbsolute(relative)) throw new Error('Unsafe manifest path');
-    const file = path.join(root, engine.root, relative);
-    if (fs.lstatSync(file).isSymbolicLink()) throw new Error('Unsafe vendored symlink');
-    if (crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex') !== expected) throw new Error(`Runtime drift: ${relative}`);
-    if (relative.endsWith('.js')) { const syntax = spawnSync(process.execPath, ['--check', file], { windowsHide: true, encoding: 'utf8' }); if (syntax.status !== 0) throw new Error(`Runtime syntax error: ${relative}`); }
-    if (hasGit && !workingTree) {
-      const indexed = spawnSync('git', ['show', `:${engine.root}/${relative}`], { cwd: root, windowsHide: true });
-      if (indexed.status !== 0) throw new Error(`Release blocked: runtime file is not Git tracked: ${relative}`);
-      if (crypto.createHash('sha256').update(indexed.stdout).digest('hex') !== expected) throw new Error(`Release blocked: Git runtime bytes differ from manifest: ${relative}`);
-    }
-  }
-  const enginePackage = JSON.parse(fs.readFileSync(path.join(root, engine.root, 'package.json')));
-  if (enginePackage.version !== engine.version || Object.keys(enginePackage.dependencies || {}).length || Object.keys(enginePackage.devDependencies || {}).length) throw new Error('Engine version/dependency contract failed');
-  process.stdout.write(workingTree ? 'Runtime content verified; uncommitted working tree is not release approval.\n' : 'Vendored runtime release gate passed.\n');
-}
-if (require.main === module) { try { verify(); } catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; } }
-module.exports = { isPinnedModuleVersion };
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+const root = path.resolve(__dirname, '../..');
+const workingTree = process.argv.includes('--working-tree');
+function isPinnedModuleVersion(name, value) {
+  const version = name === 'claude-ai-workbench' ? String(value || '').replace(/^npm:@sanqianx\/claude-ai-workbench@/, '') : value;
+  return /^\d+\.\d+\.\d+(?:-rc\.\d+)?$/.test(version || '');
+}
+function verify() {
+  const manifest = JSON.parse(fs.readFileSync(path.join(root, 'vendor-manifest.json'), 'utf8'));
+  if (manifest.schema !== 'project-knowledge/vendor-runtime/v1') throw new Error('Invalid runtime manifest');
+  const engine = manifest.modules['knowledge-engine'];
+  if (!engine || engine.root !== '_modules/knowledge-engine') throw new Error('Missing engine runtime');
+  const packageInfo = JSON.parse(fs.readFileSync(path.join(root, 'package.json')));
+  for (const dependency of ['claude-ai-workbench', '@sanqianx/vector-hub', '@sanqianx/ai-coding-event-bridge-console']) {
+    if (!isPinnedModuleVersion(dependency, packageInfo.dependencies[dependency])) throw new Error(`Module dependency must be pinned: ${dependency}`);
+  }
+  const required = ['package.json', 'src/bin.js', 'src/server.js', 'src/coordinator.js', 'src/analysis-worker.js', 'ui/index.html', 'ui/app.js', 'ui/app.css'];
+  if (required.some(file => !engine.files[file])) throw new Error('Incomplete runtime manifest');
+  const hasGit = fs.existsSync(path.join(root, '.git'));
+  function checkTree(directory, prefix = '') {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const relative = prefix + entry.name;
+      if (entry.isSymbolicLink()) throw new Error(`Unsafe runtime path: ${relative}`);
+      if (entry.isDirectory()) checkTree(path.join(directory, entry.name), relative + '/');
+      else if (!Object.hasOwn(engine.files, relative)) throw new Error(`Unreviewed runtime file: ${relative}`);
+    }
+  }
+  checkTree(path.join(root, engine.root));
+  for (const [relative, expected] of Object.entries(engine.files)) {
+    if (relative.includes('..') || path.isAbsolute(relative)) throw new Error('Unsafe manifest path');
+    const file = path.join(root, engine.root, relative);
+    if (fs.lstatSync(file).isSymbolicLink()) throw new Error('Unsafe vendored symlink');
+    if (crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex') !== expected) throw new Error(`Runtime drift: ${relative}`);
+    if (relative.endsWith('.js')) { const syntax = spawnSync(process.execPath, ['--check', file], { windowsHide: true, encoding: 'utf8' }); if (syntax.status !== 0) throw new Error(`Runtime syntax error: ${relative}`); }
+    if (hasGit && !workingTree) {
+      const indexed = spawnSync('git', ['show', `:${engine.root}/${relative}`], { cwd: root, windowsHide: true });
+      if (indexed.status !== 0) throw new Error(`Release blocked: runtime file is not Git tracked: ${relative}`);
+      if (crypto.createHash('sha256').update(indexed.stdout).digest('hex') !== expected) throw new Error(`Release blocked: Git runtime bytes differ from manifest: ${relative}`);
+    }
+  }
+  const enginePackage = JSON.parse(fs.readFileSync(path.join(root, engine.root, 'package.json')));
+  if (enginePackage.version !== engine.version || Object.keys(enginePackage.dependencies || {}).length || Object.keys(enginePackage.devDependencies || {}).length) throw new Error('Engine version/dependency contract failed');
+  process.stdout.write(workingTree ? 'Runtime content verified; uncommitted working tree is not release approval.\n' : 'Vendored runtime release gate passed.\n');
+}
+if (require.main === module) { try { verify(); } catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; } }
+module.exports = { isPinnedModuleVersion };

package/_site/scripts/verify-product-runtime.js

@@ -1,36 +1,36 @@
-'use strict';
-const fs = require('node:fs');
-const path = require('node:path');
-const crypto = require('node:crypto');
-const { createRequire } = require('node:module');
-const { safeRelative } = require('./pack-module-candidates');
-function verifyProductRuntime(coreRoot, resolveFrom = path.join(coreRoot, 'package.json')) {
-  const manifest = JSON.parse(fs.readFileSync(path.join(coreRoot, 'module-runtime-manifest.json')));
-  if (manifest.schema !== 'project-knowledge/module-content/v1' || Object.keys(manifest.modules).length !== 3) throw new Error('Incomplete module content manifest');
-  for (const file of ['ui/index.html', 'ui/knowledge-panel.html', 'ui/product.js', 'ui/product.css', 'ui/favicon.svg', 'plugins/project-knowledge/hooks/claude.json', 'plugins/project-knowledge/hooks/codex.json', 'plugins/project-knowledge/scripts/context-hook.cjs', 'plugins/project-knowledge/scripts/mcp-launcher.cjs', 'plugins/project-knowledge/.claude-plugin/plugin.json', 'plugins/project-knowledge/.codex-plugin/plugin.json', 'plugins/project-knowledge/.mcp.json']) if (!manifest.productFiles?.[file]) throw new Error(`Product asset missing from content manifest: ${file}`);
-  const resolve = createRequire(resolveFrom);
-  if (!manifest.productFiles['ui/live-client.js']) throw new Error('Product live transport missing from content manifest');
-  for (const [relative, expected] of Object.entries(manifest.productFiles || {})) {
-    if (!safeRelative(relative) || crypto.createHash('sha256').update(fs.readFileSync(path.join(coreRoot, relative))).digest('hex') !== expected) throw new Error(`Product UI content mismatch: ${relative}`);
-  }
-  const modules = {};
-  for (const [key, module] of Object.entries(manifest.modules)) {
-    const pkgFile = resolve.resolve(`${module.installName}/package.json`);
-    const directory = path.dirname(pkgFile);
-    const pkg = JSON.parse(fs.readFileSync(pkgFile));
-    if (pkg.name !== module.name || pkg.version !== module.version) throw new Error(`Module version mismatch: ${key}`);
-    for (const [relative, expected] of Object.entries(module.files)) {
-      if (!safeRelative(relative) || !/^[a-f0-9]{64}$/.test(expected)) throw new Error('Unsafe module content manifest');
-      const file = path.join(directory, relative);
-      if (fs.lstatSync(file).isSymbolicLink() || crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex') !== expected) throw new Error(`Module content mismatch: ${key}/${relative}. Install the tested candidate before packaging.`);
-    }
-    modules[key] = { directory, version: pkg.version };
-  }
-  for (const file of ['ui/index.html', 'ui/knowledge-panel.html', 'ui/product.js', 'ui/product.css', '_modules/knowledge-engine/src/bin.js', '_modules/knowledge-engine/src/coordinator.js']) if (!fs.existsSync(path.join(coreRoot, file))) throw new Error(`Product runtime missing: ${file}`);
-  return modules;
-}
-if (require.main === module) {
-  try { verifyProductRuntime(path.resolve(process.argv[2] || path.join(__dirname, '../..'))); process.stdout.write('All product module versions and contents verified.\n'); }
-  catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }
-}
-module.exports = { verifyProductRuntime };
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { createRequire } = require('node:module');
+const { safeRelative } = require('./pack-module-candidates');
+function verifyProductRuntime(coreRoot, resolveFrom = path.join(coreRoot, 'package.json')) {
+  const manifest = JSON.parse(fs.readFileSync(path.join(coreRoot, 'module-runtime-manifest.json')));
+  if (manifest.schema !== 'project-knowledge/module-content/v1' || Object.keys(manifest.modules).length !== 3) throw new Error('Incomplete module content manifest');
+  for (const file of ['ui/index.html', 'ui/knowledge-panel.html', 'ui/product.js', 'ui/product.css', 'ui/favicon.svg', 'plugins/project-knowledge/hooks/claude.json', 'plugins/project-knowledge/hooks/codex.json', 'plugins/project-knowledge/scripts/context-hook.cjs', 'plugins/project-knowledge/scripts/mcp-launcher.cjs', 'plugins/project-knowledge/.claude-plugin/plugin.json', 'plugins/project-knowledge/.codex-plugin/plugin.json', 'plugins/project-knowledge/.mcp.json']) if (!manifest.productFiles?.[file]) throw new Error(`Product asset missing from content manifest: ${file}`);
+  const resolve = createRequire(resolveFrom);
+  if (!manifest.productFiles['ui/live-client.js']) throw new Error('Product live transport missing from content manifest');
+  for (const [relative, expected] of Object.entries(manifest.productFiles || {})) {
+    if (!safeRelative(relative) || crypto.createHash('sha256').update(fs.readFileSync(path.join(coreRoot, relative))).digest('hex') !== expected) throw new Error(`Product UI content mismatch: ${relative}`);
+  }
+  const modules = {};
+  for (const [key, module] of Object.entries(manifest.modules)) {
+    const pkgFile = resolve.resolve(`${module.installName}/package.json`);
+    const directory = path.dirname(pkgFile);
+    const pkg = JSON.parse(fs.readFileSync(pkgFile));
+    if (pkg.name !== module.name || pkg.version !== module.version) throw new Error(`Module version mismatch: ${key}`);
+    for (const [relative, expected] of Object.entries(module.files)) {
+      if (!safeRelative(relative) || !/^[a-f0-9]{64}$/.test(expected)) throw new Error('Unsafe module content manifest');
+      const file = path.join(directory, relative);
+      if (fs.lstatSync(file).isSymbolicLink() || crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex') !== expected) throw new Error(`Module content mismatch: ${key}/${relative}. Install the tested candidate before packaging.`);
+    }
+    modules[key] = { directory, version: pkg.version };
+  }
+  for (const file of ['ui/index.html', 'ui/knowledge-panel.html', 'ui/product.js', 'ui/product.css', '_modules/knowledge-engine/src/bin.js', '_modules/knowledge-engine/src/coordinator.js']) if (!fs.existsSync(path.join(coreRoot, file))) throw new Error(`Product runtime missing: ${file}`);
+  return modules;
+}
+if (require.main === module) {
+  try { verifyProductRuntime(path.resolve(process.argv[2] || path.join(__dirname, '../..'))); process.stdout.write('All product module versions and contents verified.\n'); }
+  catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }
+}
+module.exports = { verifyProductRuntime };

package/_site/scripts/verify-retrieval-gold.js

@@ -1,83 +1,83 @@
-'use strict';
-const fs = require('node:fs');
-const path = require('node:path');
-const crypto = require('node:crypto');
-
-async function verify({ url, projects, fixtureRoot, queries, reportPath }) {
-  const root = path.resolve(fixtureRoot);
-  const inside = file => { const relative = path.relative(root, path.resolve(file)); return relative && !relative.startsWith('..') && !path.isAbsolute(relative); };
-  const report = { passed: false, source: 'real engine and configured remote embeddings', startedAt: new Date().toISOString(), cases: [], metrics: {} };
-  const save = () => fs.writeFileSync(reportPath, JSON.stringify(report, null, 2));
-  let semanticHits = 0, vectorCases = 0, checkedCitations = 0, badCitations = 0, scopeLeaks = 0, deepReads = 0, snippetFactHits = 0;
-  for (const q of queries) {
-    const project = projects[q.project];
-    if (!project || !inside(project.knowledgePath)) throw new Error('gold corpus must be bound to an explicit isolated fixture root');
-    const item = { id: q.id, kind: q.kind, query: q.query, passed: false };
-    let hidden, target;
-    try {
-      if (q.kind === 'stale') {
-        target = path.resolve(project.knowledgePath, q.entry);
-        if (!inside(target) || fs.lstatSync(target).isSymbolicLink()) throw new Error('unsafe stale-test path');
-        hidden = path.join(root, `gold-hidden-${q.id}.md`);
-        if (fs.existsSync(hidden)) throw new Error('prior interrupted stale test needs recovery');
-        fs.renameSync(target, hidden);
-      }
-      const response = await fetch(new URL('/api/engine/search', url), { method: 'POST', headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ projectId: project.projectId, scope: 'project', query: q.query, limit: 5 }), signal: AbortSignal.timeout(20000) });
-      const result = await response.json();
-      if (!response.ok) throw new Error(`search failed with HTTP ${response.status}`);
-      const rows = result.results || [];
-      item.health = result.health;
-      item.matchStatus = result.matchStatus;
-      item.results = rows;
-      let citationErrors = 0, leaks = 0;
-      for (const row of rows) {
-        checkedCitations++;
-        if (row.scope_project_id !== project.projectId) { leaks++; continue; }
-        const file = path.resolve(project.knowledgePath, row.entry_id);
-        if (!inside(file) || !fs.existsSync(file)) { citationErrors++; continue; }
-        const body = fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n');
-        const snippet = String(row.chunk_text || '').replace(/\r\n/g, '\n');
-        const hash = crypto.createHash('sha256').update(snippet).digest('hex');
-        if (!snippet.trim() || !body.includes(snippet) || hash !== row.content_hash) citationErrors++;
-      }
-      badCitations += citationErrors; scopeLeaks += leaks;
-      const documentHit = rows.some(row => row.entry_id === q.entry);
-      const snippetFactHit = rows.some(row => row.entry_id === q.entry && (!q.fact || String(row.chunk_text).toLowerCase().includes(q.fact.toLowerCase())));
-      let factRetrieved = snippetFactHit;
-      if (q.fact && documentHit && !snippetFactHit) {
-        // Search locates documents; an agent may then get the selected entry.
-        // Record this separately rather than claiming a snippet contained it.
-        const detail = await fetch(new URL('/api/engine/get', url), { method: 'POST', headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ projectId: project.projectId, entryId: q.entry, scope: 'project' }), signal: AbortSignal.timeout(10000) });
-        const full = await detail.json();
-        const text = full.chunks?.map(chunk => chunk.chunk_text).join('\n') || '';
-        const source = fs.readFileSync(path.resolve(project.knowledgePath, q.entry), 'utf8');
-        factRetrieved = detail.ok && text === source && text.toLowerCase().includes(q.fact.toLowerCase());
-        item.followupRead = { entry: q.entry, passed: factRetrieved, sha256: crypto.createHash('sha256').update(text).digest('hex') };
-        deepReads++;
-      }
-      item.documentHit = documentHit; item.snippetFactHit = snippetFactHit;
-      const vector = rows.some(row => row.match_channels?.includes('index:vector-hub')) && result.health?.vectorMode === 'verified-chunks';
-      if (q.kind === 'semantic') { if (documentHit) semanticHits++; if (vector) vectorCases++; if (snippetFactHit) snippetFactHits++; }
-      item.passed = !citationErrors && !leaks && (q.empty ? rows.length === 0
-        : q.kind === 'stale' ? rows.every(row => row.entry_id !== q.entry)
-        : q.kind === 'isolation' ? true : documentHit && factRetrieved && (q.kind !== 'semantic' || vector));
-      item.citationErrors = citationErrors; item.scopeLeaks = leaks;
-    } catch (error) { item.error = error.message; }
-    finally { if (hidden && fs.existsSync(hidden)) { if (fs.existsSync(target)) throw new Error('stale-test source changed concurrently; backup retained'); fs.renameSync(hidden, target); } }
-    report.cases.push(item); save();
-    console.log(`${item.passed ? 'PASS' : 'FAIL'} ${q.id} ${q.kind}`);
-  }
-  report.metrics = { semanticRecallAt5: semanticHits / queries.filter(q => q.kind === 'semantic').length, semanticSnippetFactCoverage: snippetFactHits / 10, followupEntryReads: deepReads, semanticVectorCases: vectorCases, checkedCitations, badCitations, scopeLeaks };
-  report.passed = report.cases.every(c => c.passed) && report.metrics.semanticRecallAt5 >= 0.9 && vectorCases === 10 && !badCitations && !scopeLeaks;
-  report.finishedAt = new Date().toISOString(); save();
-  return report;
-}
-
-if (require.main === module) {
-  const env = JSON.parse(fs.readFileSync(path.resolve(process.argv[2]), 'utf8'));
-  const queries = JSON.parse(fs.readFileSync(path.resolve(__dirname, '../_test/fixtures/retrieval-gold-queries.json'), 'utf8'));
-  verify({ ...env, queries, reportPath: path.resolve(process.argv[3]) }).then(report => { console.log(JSON.stringify(report.metrics)); process.exitCode = report.passed ? 0 : 1; }).catch(error => { console.error(error.message); process.exitCode = 1; });
-}
-module.exports = { verify };
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+async function verify({ url, projects, fixtureRoot, queries, reportPath }) {
+  const root = path.resolve(fixtureRoot);
+  const inside = file => { const relative = path.relative(root, path.resolve(file)); return relative && !relative.startsWith('..') && !path.isAbsolute(relative); };
+  const report = { passed: false, source: 'real engine and configured remote embeddings', startedAt: new Date().toISOString(), cases: [], metrics: {} };
+  const save = () => fs.writeFileSync(reportPath, JSON.stringify(report, null, 2));
+  let semanticHits = 0, vectorCases = 0, checkedCitations = 0, badCitations = 0, scopeLeaks = 0, deepReads = 0, snippetFactHits = 0;
+  for (const q of queries) {
+    const project = projects[q.project];
+    if (!project || !inside(project.knowledgePath)) throw new Error('gold corpus must be bound to an explicit isolated fixture root');
+    const item = { id: q.id, kind: q.kind, query: q.query, passed: false };
+    let hidden, target;
+    try {
+      if (q.kind === 'stale') {
+        target = path.resolve(project.knowledgePath, q.entry);
+        if (!inside(target) || fs.lstatSync(target).isSymbolicLink()) throw new Error('unsafe stale-test path');
+        hidden = path.join(root, `gold-hidden-${q.id}.md`);
+        if (fs.existsSync(hidden)) throw new Error('prior interrupted stale test needs recovery');
+        fs.renameSync(target, hidden);
+      }
+      const response = await fetch(new URL('/api/engine/search', url), { method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ projectId: project.projectId, scope: 'project', query: q.query, limit: 5 }), signal: AbortSignal.timeout(20000) });
+      const result = await response.json();
+      if (!response.ok) throw new Error(`search failed with HTTP ${response.status}`);
+      const rows = result.results || [];
+      item.health = result.health;
+      item.matchStatus = result.matchStatus;
+      item.results = rows;
+      let citationErrors = 0, leaks = 0;
+      for (const row of rows) {
+        checkedCitations++;
+        if (row.scope_project_id !== project.projectId) { leaks++; continue; }
+        const file = path.resolve(project.knowledgePath, row.entry_id);
+        if (!inside(file) || !fs.existsSync(file)) { citationErrors++; continue; }
+        const body = fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n');
+        const snippet = String(row.chunk_text || '').replace(/\r\n/g, '\n');
+        const hash = crypto.createHash('sha256').update(snippet).digest('hex');
+        if (!snippet.trim() || !body.includes(snippet) || hash !== row.content_hash) citationErrors++;
+      }
+      badCitations += citationErrors; scopeLeaks += leaks;
+      const documentHit = rows.some(row => row.entry_id === q.entry);
+      const snippetFactHit = rows.some(row => row.entry_id === q.entry && (!q.fact || String(row.chunk_text).toLowerCase().includes(q.fact.toLowerCase())));
+      let factRetrieved = snippetFactHit;
+      if (q.fact && documentHit && !snippetFactHit) {
+        // Search locates documents; an agent may then get the selected entry.
+        // Record this separately rather than claiming a snippet contained it.
+        const detail = await fetch(new URL('/api/engine/get', url), { method: 'POST', headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ projectId: project.projectId, entryId: q.entry, scope: 'project' }), signal: AbortSignal.timeout(10000) });
+        const full = await detail.json();
+        const text = full.chunks?.map(chunk => chunk.chunk_text).join('\n') || '';
+        const source = fs.readFileSync(path.resolve(project.knowledgePath, q.entry), 'utf8');
+        factRetrieved = detail.ok && text === source && text.toLowerCase().includes(q.fact.toLowerCase());
+        item.followupRead = { entry: q.entry, passed: factRetrieved, sha256: crypto.createHash('sha256').update(text).digest('hex') };
+        deepReads++;
+      }
+      item.documentHit = documentHit; item.snippetFactHit = snippetFactHit;
+      const vector = rows.some(row => row.match_channels?.includes('index:vector-hub')) && result.health?.vectorMode === 'verified-chunks';
+      if (q.kind === 'semantic') { if (documentHit) semanticHits++; if (vector) vectorCases++; if (snippetFactHit) snippetFactHits++; }
+      item.passed = !citationErrors && !leaks && (q.empty ? rows.length === 0
+        : q.kind === 'stale' ? rows.every(row => row.entry_id !== q.entry)
+        : q.kind === 'isolation' ? true : documentHit && factRetrieved && (q.kind !== 'semantic' || vector));
+      item.citationErrors = citationErrors; item.scopeLeaks = leaks;
+    } catch (error) { item.error = error.message; }
+    finally { if (hidden && fs.existsSync(hidden)) { if (fs.existsSync(target)) throw new Error('stale-test source changed concurrently; backup retained'); fs.renameSync(hidden, target); } }
+    report.cases.push(item); save();
+    console.log(`${item.passed ? 'PASS' : 'FAIL'} ${q.id} ${q.kind}`);
+  }
+  report.metrics = { semanticRecallAt5: semanticHits / queries.filter(q => q.kind === 'semantic').length, semanticSnippetFactCoverage: snippetFactHits / 10, followupEntryReads: deepReads, semanticVectorCases: vectorCases, checkedCitations, badCitations, scopeLeaks };
+  report.passed = report.cases.every(c => c.passed) && report.metrics.semanticRecallAt5 >= 0.9 && vectorCases === 10 && !badCitations && !scopeLeaks;
+  report.finishedAt = new Date().toISOString(); save();
+  return report;
+}
+
+if (require.main === module) {
+  const env = JSON.parse(fs.readFileSync(path.resolve(process.argv[2]), 'utf8'));
+  const queries = JSON.parse(fs.readFileSync(path.resolve(__dirname, '../_test/fixtures/retrieval-gold-queries.json'), 'utf8'));
+  verify({ ...env, queries, reportPath: path.resolve(process.argv[3]) }).then(report => { console.log(JSON.stringify(report.metrics)); process.exitCode = report.passed ? 0 : 1; }).catch(error => { console.error(error.message); process.exitCode = 1; });
+}
+module.exports = { verify };

package/_site/server.js

@@ -1,15 +1,15 @@
-// Project Knowledge v2 HTTP entry point.
-const { startServer, installProcessHandlers } = require('./lib/server-app');
-
-const instancePromise = startServer();
-installProcessHandlers(instancePromise);
-module.exports = instancePromise;
-
-instancePromise.then(instance => {
-  process.stdout.write(`Project Knowledge listening on http://${instance.host}:${instance.port}\n`);
-}).catch(error => {
-  if (require.main === module) {
-    process.stderr.write(`[project-knowledge] startup failed: ${String(error && error.message || error)}\n`);
-    process.exitCode = 1;
-  }
-});
+// Project Knowledge v2 HTTP entry point.
+const { startServer, installProcessHandlers } = require('./lib/server-app');
+
+const instancePromise = startServer();
+installProcessHandlers(instancePromise);
+module.exports = instancePromise;
+
+instancePromise.then(instance => {
+  process.stdout.write(`Project Knowledge listening on http://${instance.host}:${instance.port}\n`);
+}).catch(error => {
+  if (require.main === module) {
+    process.stderr.write(`[project-knowledge] startup failed: ${String(error && error.message || error)}\n`);
+    process.exitCode = 1;
+  }
+});

package/_site/start.bat

@@ -1,26 +1,26 @@
-@echo off
-setlocal
-
-REM KB Management Site launcher — double-click to start
-set KB_SITE=%~dp0
-set PORT=5757
-
-REM Check if already running
-netstat -ano | findstr ":%PORT% " | findstr "LISTENING" >nul 2>&1
-if %ERRORLEVEL%==0 (
-  echo [kb-site] Already running on port %PORT%. Opening browser...
-  start "" "http://localhost:%PORT%/"
-  goto :eof
-)
-
-echo [kb-site] Starting server on port %PORT%...
-start "KB-Site" /min cmd /c "cd /d "%KB_SITE%" && node server.js"
-timeout /t 2 /nobreak >nul
-
-REM Open browser
-start "" "http://localhost:%PORT%/"
-
-echo.
-echo [kb-site] Server started. To stop: close the "KB-Site" window, or run stop.bat
-echo.
-pause
+@echo off
+setlocal
+
+REM KB Management Site launcher — double-click to start
+set KB_SITE=%~dp0
+set PORT=5757
+
+REM Check if already running
+netstat -ano | findstr ":%PORT% " | findstr "LISTENING" >nul 2>&1
+if %ERRORLEVEL%==0 (
+  echo [kb-site] Already running on port %PORT%. Opening browser...
+  start "" "http://localhost:%PORT%/"
+  goto :eof
+)
+
+echo [kb-site] Starting server on port %PORT%...
+start "KB-Site" /min cmd /c "cd /d "%KB_SITE%" && node server.js"
+timeout /t 2 /nobreak >nul
+
+REM Open browser
+start "" "http://localhost:%PORT%/"
+
+echo.
+echo [kb-site] Server started. To stop: close the "KB-Site" window, or run stop.bat
+echo.
+pause

package/_site/stop.bat

@@ -1,11 +1,11 @@
-@echo off
-setlocal
-set PORT=5757
-
-echo [kb-site] Stopping server on port %PORT%...
-for /f "tokens=5" %%P in ('netstat -ano ^| findstr ":%PORT% " ^| findstr "LISTENING"') do (
-  taskkill /F /PID %%P >nul 2>&1
-  echo [kb-site] Killed PID %%P
-)
-echo Done.
-pause
+@echo off
+setlocal
+set PORT=5757
+
+echo [kb-site] Stopping server on port %PORT%...
+for /f "tokens=5" %%P in ('netstat -ano ^| findstr ":%PORT% " ^| findstr "LISTENING"') do (
+  taskkill /F /PID %%P >nul 2>&1
+  echo [kb-site] Killed PID %%P
+)
+echo Done.
+pause