@sanqianx/project-knowledge 4.6.1

package/_site/_test/logging-sse-no-gap-test.js

@@ -0,0 +1,88 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnServer } = require('./helpers/spawn-server');
+const { StorageLayout } = require('../lib/storage-layout');
+const { LogRepository } = require('../lib/structured-logger');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const PORT = 7950 + (process.pid % 300);
+const BASE = `http://127.0.0.1:${PORT}`;
+
+async function waitForServer() {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    try { if ((await fetch(`${BASE}/api/health`)).ok) return; } catch {}
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  throw new Error('server did not start');
+}
+
+(async () => {
+  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-log-sse-'));
+  const spawned = spawnServer({ root: ROOT, port: PORT, dataDir, tag: 'log-sse', extraEnv: { KB_SKIP_MIGRATION: '1' } });
+  try {
+    await waitForServer();
+    let response = await fetch(`${BASE}/api/logs?q=http.request_`);
+    let snapshot = await response.json();
+    assert.strictEqual(snapshot.pageSize, 500, 'HTTP logs API must preserve the 500-row default');
+    assert(snapshot.streamCursor);
+    response = await fetch(`${BASE}/api/logs?pageSize=999999`);
+    assert.strictEqual((await response.json()).pageSize, 5000, 'HTTP logs API must cap the display page at 5000');
+
+    await fetch(`${BASE}/api/state`);
+    await fetch(`${BASE}/api/projects/not-valid%2Fid`);
+    await new Promise(resolve => setTimeout(resolve, 100));
+    const watermark = JSON.parse(Buffer.from(snapshot.streamCursor, 'base64url').toString('utf8'));
+    const repository = new LogRepository({ layout: new StorageLayout({ dataDir }) });
+    const page = repository.query({ q: 'http.request_', pageSize: 5000 });
+    const expectedGapIds = [];
+    for (const entry of page.entries) {
+      if (entry.id === watermark.afterId) break;
+      expectedGapIds.push(entry.id);
+    }
+    assert(expectedGapIds.length >= 3, 'fixture must create completed and failed requests between GET and SSE');
+
+    const controller = new AbortController();
+    response = await fetch(`${BASE}/api/logs/stream?q=http.request_&streamCursor=${encodeURIComponent(snapshot.streamCursor)}`, { signal: controller.signal });
+    assert.strictEqual(response.status, 200);
+    assert.match(response.headers.get('content-type'), /text\/event-stream/);
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let pending = '';
+    const streamedIds = new Set();
+    let ready = false;
+    const deadline = Date.now() + 5000;
+    while (Date.now() < deadline && (!ready || expectedGapIds.some(id => !streamedIds.has(id)))) {
+      const read = await Promise.race([
+        reader.read(),
+        new Promise((_, reject) => setTimeout(() => reject(new Error('SSE read timeout')), 1000)),
+      ]);
+      if (read.done) break;
+      pending += decoder.decode(read.value, { stream: true });
+      const frames = pending.split('\n\n');
+      pending = frames.pop() || '';
+      for (const frame of frames) {
+        const dataLine = frame.split('\n').find(line => line.startsWith('data: '));
+        if (!dataLine) continue;
+        const event = JSON.parse(dataLine.slice(6));
+        if (event.type === 'logs/ready') ready = true;
+        if (event.type === 'logs/appended' && event.record) streamedIds.add(event.record.id);
+      }
+    }
+    controller.abort();
+    assert(ready, 'SSE must mark the replay/live handoff');
+    assert(expectedGapIds.every(id => streamedIds.has(id)), 'GET-to-SSE handoff must replay every durable gap record exactly by id');
+
+    const requestLogs = repository.query({ q: 'http.request_', pageSize: 5000 }).entries;
+    assert(requestLogs.some(entry => entry.event === 'http.request_started'));
+    assert(requestLogs.some(entry => entry.event === 'http.request_completed' && entry.durationMs >= 0));
+    assert(requestLogs.some(entry => entry.event === 'http.request_failed' && entry.operationId));
+    console.log('logging-sse-no-gap-test PASS');
+  } finally {
+    await spawned.cleanup();
+  }
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+});

package/_site/_test/logging-ui-test.js

@@ -0,0 +1,104 @@
+const assert = require('assert');
+const path = require('path');
+const { spawnServer } = require('./helpers/spawn-server');
+const { requestJson, waitFor } = require('./helpers/cdp-browser');
+const { createLoggingUiFixture } = require('./helpers/logging-ui-fixture');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const port = 8750 + (process.pid % 180);
+
+function baseParams(fixture, pageSize) {
+  const params = new URLSearchParams();
+  params.set('from', '2000-01-01');
+  params.set('to', '2999-12-31');
+  params.set('levels', 'trace,debug,info,warn,error,fatal');
+  params.set('projectId', fixture.projectId);
+  params.set('pageSize', String(pageSize || 10));
+  return params;
+}
+
+async function jsonResponse(url) {
+  const response = await fetch(url, { headers: { Accept: 'application/json' } });
+  const body = await response.json();
+  return { response, body };
+}
+
+(async () => {
+  const fixture = await createLoggingUiFixture({ totalLogs: 64 });
+  const server = spawnServer({ root: ROOT, port, dataDir: fixture.dataDir, tag: 'logging-ui-api', stdio: 'ignore' });
+  try {
+    await waitFor(() => requestJson('http://127.0.0.1:' + port + '/api/health').then(body => body.ok), 'logging API', 20000);
+    const baseUrl = 'http://127.0.0.1:' + port;
+    const firstParams = baseParams(fixture, 10);
+    const first = await jsonResponse(baseUrl + '/api/logs?' + firstParams.toString());
+    assert.strictEqual(first.response.status, 200);
+    assert.strictEqual(first.body.entries.length, 10);
+    assert(first.body.nextCursor, 'first page must return an opaque next cursor');
+    assert.strictEqual(first.body.pageSize, 10);
+    assert(first.body.health && first.body.health.status === 'ok');
+    assert.deepStrictEqual(Object.keys(first.body.counts).sort(), ['debug', 'error', 'fatal', 'info', 'trace', 'warn']);
+
+    const secondParams = baseParams(fixture, 10);
+    secondParams.set('cursor', first.body.nextCursor);
+    const second = await jsonResponse(baseUrl + '/api/logs?' + secondParams.toString());
+    assert.strictEqual(second.response.status, 200);
+    assert.strictEqual(second.body.entries.length, 10);
+    assert(!second.body.entries.some(entry => first.body.entries.some(prior => prior.id === entry.id)), 'cursor pages must not overlap');
+
+    const invalidParams = baseParams(fixture, 10);
+    invalidParams.set('cursor', first.body.nextCursor);
+    invalidParams.set('q', 'changed-fingerprint');
+    const invalid = await jsonResponse(baseUrl + '/api/logs?' + invalidParams.toString());
+    assert.strictEqual(invalid.response.status, 409);
+    assert.strictEqual(invalid.body.error.code, 'LOG_CURSOR_EXPIRED');
+    assert.strictEqual(invalid.body.error.retryable, true);
+    assert(!('stack' in invalid.body.error), 'public cursor error must not leak a stack');
+
+    const filters = [
+      ['component', 'commit-reconciler'],
+      ['event', 'fixture.phase.10'],
+      ['operationId', 'op-flow-visual'],
+      ['commitSha', fixture.repo.headCommit],
+      ['q', '<img src=x onerror=window.__xss=1>'],
+      ['levels', 'fatal'],
+    ];
+    for (const pair of filters) {
+      const params = baseParams(fixture, 100);
+      params.set(pair[0], pair[1]);
+      const result = await jsonResponse(baseUrl + '/api/logs?' + params.toString());
+      assert.strictEqual(result.response.status, 200, 'filter failed: ' + pair[0]);
+      assert(result.body.entries.length > 0, 'filter returned no entries: ' + pair[0]);
+    }
+
+    const exportParams = baseParams(fixture, 100);
+    exportParams.delete('pageSize');
+    exportParams.set('operationId', 'op-flow-visual');
+    exportParams.set('component', 'commit-reconciler');
+    exportParams.set('event', 'fixture.phase.3');
+    exportParams.set('commitSha', fixture.repo.headCommit);
+    const exported = await fetch(baseUrl + '/api/logs/export?' + exportParams.toString(), { headers: { Accept: 'application/x-ndjson' } });
+    assert.strictEqual(exported.status, 200);
+    assert((exported.headers.get('content-type') || '').includes('application/x-ndjson'));
+    assert((exported.headers.get('content-disposition') || '').includes('attachment'));
+    const lines = (await exported.text()).trim().split(/\r?\n/).filter(Boolean).map(line => JSON.parse(line));
+    assert.strictEqual(lines.length, 1);
+    assert(lines.every(entry => entry.operationId === 'op-flow-visual' && entry.component === 'commit-reconciler' && entry.event === 'fixture.phase.3'));
+
+    const rootMutation = await fetch(baseUrl + '/api/settings', {
+      method: 'PATCH',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ logging: { rootPath: path.join(fixture.dataDir, 'elsewhere') } }),
+    });
+    assert.strictEqual(rootMutation.status, 409, 'logging root must not be mutable through the API');
+    const persistedSettings = JSON.parse(require('fs').readFileSync(fixture.layout.getSettingsPath(), 'utf8'));
+    assert(!Object.prototype.hasOwnProperty.call(persistedSettings.logging, 'rootPath'));
+
+    console.log('logging UI test PASS');
+  } finally {
+    await server.cleanup();
+    fixture.cleanup();
+  }
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+});

package/_site/_test/markdown-delta-overlay-test.js

@@ -0,0 +1,85 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const AtomicFile = require('../lib/atomic-file');
+const { StorageLayout } = require('../lib/storage-layout');
+const { ProjectRegistryStore } = require('../lib/project-registry-store');
+const { ProjectStore } = require('../lib/project-store');
+const { KnowledgeRetrievalService } = require('../lib/knowledge-retrieval-service');
+const { CHUNKER_VERSION } = require('../lib/markdown-knowledge-indexer');
+const { sha256 } = require('../lib/knowledge-schema');
+
+(async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-delta-overlay-'));
+  const layout = new StorageLayout({ dataDir: path.join(root, 'data') });
+  const registry = new ProjectRegistryStore({ layout });
+  const projects = new ProjectStore({ layout });
+  await registry.initialize();
+  const projectId = 'project-delta';
+  const knowledgePath = path.join(root, 'knowledge');
+  fs.mkdirSync(path.join(knowledgePath, 'modules'), { recursive: true });
+  const changedPath = path.join(knowledgePath, 'modules', 'changed.md');
+  const deletedPath = path.join(knowledgePath, 'modules', 'deleted.md');
+  const oldChanged = '# Changed\n\nStale token policy from C0.\n';
+  const oldDeleted = '# Deleted\n\nStale deleted knowledge.\n';
+  fs.writeFileSync(changedPath, oldChanged, 'utf8');
+  fs.writeFileSync(deletedPath, oldDeleted, 'utf8');
+  await projects.create(projectId, {
+    displayName: 'Delta', storageName: 'delta', repoPath: root, knowledgePath,
+  }, { index: { dirty: true, generation: 2, sinceCommit: '1'.repeat(40) } });
+  await registry.add(projectId, { displayNameSnapshot: 'Delta' });
+  AtomicFile.writeJsonAtomic(layout.getRuntimePath('index-sources', `${projectId}.json`), {
+    schema: 'knowledge-index-source-manifest/v1',
+    projectId,
+    generation: 1,
+    entries: {
+      'modules/changed.md': { entryId: 'modules/changed.md', documentHash: sha256(`chunker:${CHUNKER_VERSION}\n${oldChanged}`), sourceCommit: '0'.repeat(40) },
+      'modules/deleted.md': { entryId: 'modules/deleted.md', documentHash: sha256(`chunker:${CHUNKER_VERSION}\n${oldDeleted}`), sourceCommit: '0'.repeat(40) },
+    },
+  });
+
+  const currentChanged = `---\nsourcePaths: [src/token-policy.js]\n---\n# Changed\n\nC1 current rotating token policy truth.\n`;
+  fs.writeFileSync(changedPath, currentChanged, 'utf8');
+  fs.unlinkSync(deletedPath);
+  fs.writeFileSync(path.join(knowledgePath, 'modules', 'new.md'), `---\ntags: [token-policy]\n---\n# New\n\nC1 newly documented policy.\n`, 'utf8');
+  fs.mkdirSync(layout.getIndexPath(), { recursive: true });
+
+  const staleRows = [{
+    record_id: 'project:project-delta:modules/changed.md:0',
+    space_id: 'project:project-delta', entry_id: 'modules/changed.md', chunk_id: 'modules/changed.md:0', chunk_order: 0,
+    title: 'Changed', chunk_text: oldChanged, document_hash: sha256(`chunker:${CHUNKER_VERSION}\n${oldChanged}`),
+    relevance_score: 1, match_channels: ['semantic'],
+  }, {
+    record_id: 'project:project-delta:modules/deleted.md:0',
+    space_id: 'project:project-delta', entry_id: 'modules/deleted.md', chunk_id: 'modules/deleted.md:0', chunk_order: 0,
+    title: 'Deleted', chunk_text: oldDeleted, document_hash: sha256(`chunker:${CHUNKER_VERSION}\n${oldDeleted}`),
+    relevance_score: 2, match_channels: ['semantic'],
+  }];
+  const service = new KnowledgeRetrievalService({
+    layout, registryStore: registry, projectStore: projects,
+    databaseProvider: () => ({ hybridSearch: async () => staleRows }),
+    embedderProvider: () => ({ embedQuery: async () => [1] }),
+  });
+  const result = await service.retrieveForCommit({
+    projectId,
+    conversationSnapshot: { turns: [{ userEvents: [{ content: 'Update rotating token policy.' }], assistantEvents: [] }] },
+    commitEvidence: { commitSha: '1'.repeat(40), subject: 'token policy', files: [{ status: 'M', path: 'src/token-policy.js' }] },
+  });
+  const changed = result.entries.find(entry => entry.path === 'modules/changed.md');
+  const added = result.entries.find(entry => entry.path === 'modules/new.md');
+  assert(changed && /C1 current/.test(changed.content), 'stale index content must be replaced by current Markdown truth');
+  assert(!result.entries.some(entry => /Stale token policy/.test(entry.content)), 'stale chunk text must never reach the prompt context');
+  assert(!result.entries.some(entry => entry.path === 'modules/deleted.md'), 'deleted Markdown must be removed from stale candidates');
+  assert(changed.selectionSignals.includes('markdown-delta-overlay'));
+  assert(added && added.selectionSignals.includes('markdown-delta-overlay'), 'new Markdown must enter the in-memory delta overlay immediately');
+  assert.strictEqual(result.manifest.health.scopes[0].overlayEntries, 2);
+  assert.strictEqual(result.manifest.health.scopes[0].deletedEntries, 1);
+  assert.strictEqual(result.manifest.backend, 'ok', 'a stale index may contribute recall while current Markdown remains truth');
+  assert.strictEqual(changed.documentHash, sha256(`chunker:${CHUNKER_VERSION}\n${currentChanged}`), 'retrieval manifest must freeze the current document hash');
+  assert.strictEqual(projects.readState(projectId).index.dirty, true, 'retrieval must not wait for or mutate index completion state');
+  console.log('markdown-delta-overlay-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+});

package/_site/_test/markdown-maintenance-api-test.js

@@ -0,0 +1,75 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { spawnServer } = require('./helpers/spawn-server');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const PORT = 7932;
+const BASE_URL = `http://127.0.0.1:${PORT}`;
+const TEMP = fs.mkdtempSync(path.join(os.tmpdir(), 'index-maintenance-api-v2-'));
+const DATA_DIR = path.join(TEMP, 'data');
+const REPO = path.join(TEMP, 'repo');
+
+function git(args) { return execFileSync('git', args, { cwd: REPO, encoding: 'utf8' }).trim(); }
+
+async function json(method, route, body) {
+  const response = await fetch(`${BASE_URL}${route}`, {
+    method,
+    headers: body ? { 'Content-Type': 'application/json' } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await response.text();
+  const data = text ? JSON.parse(text) : {};
+  if (!response.ok) throw new Error(`${response.status}: ${JSON.stringify(data)}`);
+  return data;
+}
+
+(async () => {
+  fs.mkdirSync(REPO, { recursive: true });
+  git(['init', '--initial-branch=main']);
+  git(['config', 'user.name', 'Index Test']);
+  git(['config', 'user.email', 'index@example.test']);
+  fs.writeFileSync(path.join(REPO, 'README.md'), '# source\n', 'utf8');
+  git(['add', '.']);
+  git(['commit', '-m', 'baseline']);
+  const spawned = spawnServer({ root: ROOT, port: PORT, dataDir: DATA_DIR, tag: 'index-maintenance-v2', extraEnv: { KB_EMBEDDING_FAKE: '1' } });
+  try {
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+      try { await json('GET', '/api/health'); break; } catch {
+        if (attempt === 99) throw new Error('server did not start');
+        await new Promise(resolve => setTimeout(resolve, 100));
+      }
+    }
+    await json('PATCH', '/api/settings', { knowledge: { rootPath: path.join(TEMP, 'knowledge') } });
+    const imported = await json('POST', '/api/projects/import', { projectId: 'maintenance-demo', localPath: REPO, displayName: 'Maintenance demo' });
+    const kbPath = imported.config.knowledgePath;
+    fs.mkdirSync(path.join(kbPath, 'modules'), { recursive: true });
+    fs.writeFileSync(path.join(kbPath, 'GOAL.md'), '# Goal\n\nBuild reliable derived indexes.\n', 'utf8');
+    fs.writeFileSync(path.join(kbPath, 'modules', 'core.md'), '# Core\n\nSingle writer atomic rebuild content.\n', 'utf8');
+    const markdownBefore = fs.readFileSync(path.join(kbPath, 'modules', 'core.md'), 'utf8');
+
+    const before = await json('GET', '/api/knowledge/maintenance');
+    assert.strictEqual(before.indexPath, path.join(DATA_DIR, 'index', 'knowledge.lancedb'));
+    const rebuilt = await json('POST', '/api/knowledge/maintenance/rebuild', {});
+    assert(rebuilt.ok && rebuilt.validation.ok, JSON.stringify(rebuilt));
+    assert(fs.existsSync(before.indexPath));
+    assert.strictEqual(fs.readFileSync(path.join(kbPath, 'modules', 'core.md'), 'utf8'), markdownBefore, 'index maintenance must not rewrite authoritative Markdown');
+    let search = await json('POST', '/api/knowledge/search', { projectId: 'maintenance-demo', query: 'atomic rebuild', limit: 5 });
+    assert.strictEqual(search.source, 'knowledge-retrieval-service');
+    assert.strictEqual(search.backend, 'hybrid+markdown-truth');
+    assert(search.results.some(item => item.entry_id === 'modules/core.md'));
+
+    fs.writeFileSync(path.join(kbPath, 'modules', 'core.md'), `${markdownBefore}\nSecond rebuild evidence.\n`, 'utf8');
+    const second = await json('POST', '/api/knowledge/maintenance/rebuild', {});
+    assert(second.ok && second.backup && fs.existsSync(second.backup), 'replacing a live index should retain the previous index under recovery');
+    search = await json('POST', '/api/knowledge/search', { projectId: 'maintenance-demo', query: 'Second rebuild evidence', limit: 5 });
+    assert(search.results.some(item => /Second rebuild evidence/.test(item.chunk_text)));
+    const after = await json('GET', '/api/knowledge/maintenance');
+    assert(after.projects.every(project => project.index.dirty === false));
+    console.log('markdown-maintenance-api-test: PASS');
+  } finally {
+    spawned.child.kill();
+  }
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/markdown-maintenance-test.js

@@ -0,0 +1,11 @@
+const assert = require('assert');
+const { canonicalRelativePath, validateMarkdown } = require('../lib/knowledge-promotion');
+
+assert.strictEqual(canonicalRelativePath('modules/core.md'), 'modules/core.md');
+for (const invalid of ['../outside.md', '/absolute.md', 'modules/00-index.md', 'module.txt', 'CON.md', 'modules/file.md:stream']) {
+  assert.throws(() => canonicalRelativePath(invalid), undefined, `unsafe promotion path should fail: ${invalid}`);
+}
+assert.doesNotThrow(() => validateMarkdown('# Verified fact\n\nEvidence-backed content.\n', 'modules/core.md'));
+assert.throws(() => validateMarkdown('# Placeholder\n\nTODO: invent this later.\n', 'modules/core.md'), /placeholder/i);
+assert.throws(() => validateMarkdown('# Title\n\n\u0000invalid', 'modules/core.md'), /control/i);
+console.log('markdown-maintenance-test: PASS');

package/_site/_test/mcp-server-test.js

@@ -0,0 +1,149 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawn, spawnSync } = require('child_process');
+const { StorageLayout } = require('../lib/storage-layout');
+const { SettingsStore } = require('../lib/settings-store');
+const { ProjectRegistryStore } = require('../lib/project-registry-store');
+const { ProjectStore } = require('../lib/project-store');
+const { ConversationStore } = require('../lib/conversation-store');
+const { KnowledgeDatabase } = require('../lib/knowledge-db');
+const { EMBEDDING_DIMENSIONS } = require('../lib/knowledge-schema');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const MCP_BIN = path.join(ROOT, 'bin', 'project-knowledge-mcp.js');
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'pkb-mcp-v2-'));
+const dataDir = path.join(temp, 'data');
+const repo = path.join(temp, 'repo');
+const vectorRepo = path.join(temp, 'vector-repo');
+const markdownKb = path.join(temp, 'knowledge-markdown');
+const vectorKb = path.join(temp, 'knowledge-vector');
+
+function write(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, 'utf8');
+}
+
+function git(cwd, args) {
+  const result = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  assert.strictEqual(result.status, 0, result.stderr);
+  return String(result.stdout || '').trim();
+}
+
+function fakeVector(text) {
+  const vector = new Array(EMBEDDING_DIMENSIONS).fill(0);
+  for (let index = 0; index < String(text).length; index += 1) vector[String(text).charCodeAt(index) % vector.length] += 1;
+  const norm = Math.sqrt(vector.reduce((sum, item) => sum + item * item, 0)) || 1;
+  return vector.map(item => item / norm);
+}
+
+async function createMcpClient() {
+  const child = spawn(process.execPath, [MCP_BIN], {
+    cwd: repo,
+    env: { ...process.env, KB_DATA_DIR: dataDir, KB_SKIP_MIGRATION: '1', KB_EMBEDDING_FAKE: '1' },
+    stdio: ['pipe', 'pipe', 'pipe'],
+    windowsHide: true,
+  });
+  let stderr = '';
+  let buffer = '';
+  let nextId = 1;
+  const pending = new Map();
+  child.stderr.on('data', chunk => { stderr += chunk; });
+  child.stdout.on('data', chunk => {
+    buffer += chunk;
+    let newline;
+    while ((newline = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      if (!line) continue;
+      const message = JSON.parse(line);
+      const entry = pending.get(message.id);
+      if (entry) { entry(message); pending.delete(message.id); }
+    }
+  });
+  const request = (method, params = {}) => new Promise((resolve, reject) => {
+    const id = nextId++;
+    const timer = setTimeout(() => { pending.delete(id); reject(new Error(`MCP timeout: ${method}\n${stderr}`)); }, 15_000);
+    pending.set(id, message => { clearTimeout(timer); resolve(message); });
+    child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`);
+  });
+  await request('initialize', { protocolVersion: '2025-03-26', capabilities: {}, clientInfo: { name: 'test', version: '1' } });
+  child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized', params: {} })}\n`);
+  return { child, request, stderr: () => stderr };
+}
+
+(async () => {
+  for (const cwd of [repo, vectorRepo]) {
+    fs.mkdirSync(cwd, { recursive: true });
+    git(cwd, ['init', '--initial-branch=main']);
+    git(cwd, ['config', 'user.email', 'mcp@example.test']);
+    git(cwd, ['config', 'user.name', 'MCP Test']);
+    write(path.join(cwd, 'README.md'), '# source\n');
+    git(cwd, ['add', 'README.md']);
+    git(cwd, ['commit', '-m', 'baseline']);
+  }
+  write(path.join(markdownKb, 'README.md'), '# Demo knowledge\n\nThis project uses rotating refresh tokens.\n');
+  write(path.join(markdownKb, 'modules', 'auth.md'), '# Authentication\n\nRefresh tokens rotate after every successful renewal.\n');
+  write(path.join(markdownKb, 'changes', 'auth.md'), '# Authentication update\n\nIntroduced rotating refresh tokens.\n');
+  write(path.join(vectorKb, 'modules', 'payments.md'), '# Payment tokens\n\nPayment tokens expire after fifteen minutes.\n');
+
+  const layout = new StorageLayout({ dataDir });
+  const settingsStore = new SettingsStore({ layout });
+  const registryStore = new ProjectRegistryStore({ layout });
+  const projectStore = new ProjectStore({ layout });
+  await settingsStore.initialize({ knowledge: { rootPath: path.join(temp, 'future-root') } });
+  await registryStore.initialize();
+  await projectStore.create('project-demo', { displayName: 'Demo', storageName: 'demo', repoPath: repo, knowledgePath: markdownKb, legacyExtensions: { slug: 'demo' } }, { trackingStartCommit: git(repo, ['rev-parse', 'HEAD']), index: { dirty: true, generation: 1 } });
+  await registryStore.add('project-demo', { displayNameSnapshot: 'Demo' });
+  await projectStore.create('project-vector', { displayName: 'Vector', storageName: 'vector', repoPath: vectorRepo, knowledgePath: vectorKb, legacyExtensions: { slug: 'vector' } }, { trackingStartCommit: git(vectorRepo, ['rev-parse', 'HEAD']) });
+  await registryStore.add('project-vector', { displayNameSnapshot: 'Vector' });
+
+  const database = new KnowledgeDatabase({ dbPath: layout.getIndexPath(), maintenancePath: layout.getRuntimePath('index-maintenance.json') });
+  await database.replaceEntry('project:project-vector', 'modules/payments.md', [{ chunkOrder: 0, title: 'Payment tokens', chunkText: 'Payment tokens expire after fifteen minutes.', vector: fakeVector('payment tokens'), sourceCommit: 'abc123' }]);
+  await database.ensureSearchIndexes();
+  await database.close();
+
+  const client = await createMcpClient();
+  try {
+    const listed = await client.request('tools/list');
+    assert.strictEqual(listed.result.tools.length, 6);
+    assert(listed.result.tools.some(tool => tool.name === 'project_knowledge_record_requirement'));
+
+    let response = await client.request('tools/call', { name: 'project_knowledge_resolve', arguments: { repoPath: repo } });
+    assert.strictEqual(response.result.structuredContent.projectId, 'project-demo');
+    assert.strictEqual(response.result.structuredContent.knowledgePath, markdownKb);
+    assert.strictEqual(response.result.structuredContent.indexPath, layout.getIndexPath());
+
+    response = await client.request('tools/call', { name: 'project_knowledge_search', arguments: { projectId: 'project-demo', query: 'refresh tokens' } });
+    assert.strictEqual(response.result.structuredContent.source, 'knowledge-retrieval-service');
+    assert.strictEqual(response.result.structuredContent.backend, 'hybrid+markdown-truth');
+    assert.strictEqual(response.result.structuredContent.health.scopes[0].dirty, true);
+    assert(response.result.structuredContent.results.some(result => result.entry_id === 'modules/auth.md'));
+
+    response = await client.request('tools/call', { name: 'project_knowledge_search', arguments: { project: 'vector', query: 'payment tokens' } });
+    assert.strictEqual(response.result.structuredContent.source, 'knowledge-retrieval-service');
+    assert.strictEqual(response.result.structuredContent.backend, 'hybrid+markdown-truth');
+    assert(response.result.structuredContent.results.some(result => result.entry_id === 'modules/payments.md'));
+
+    response = await client.request('tools/call', { name: 'project_knowledge_get', arguments: { projectId: 'project-demo', entry: 'modules/auth.md' } });
+    assert.match(response.result.structuredContent.chunks[0].chunk_text, /rotate/i);
+    response = await client.request('tools/call', { name: 'project_knowledge_history', arguments: { projectId: 'project-demo' } });
+    assert.strictEqual(response.result.structuredContent.results[0].entry_id, 'changes/auth.md');
+
+    const stateBefore = fs.readFileSync(layout.getProjectStatePath('project-demo'), 'utf8');
+    response = await client.request('tools/call', { name: 'project_knowledge_record_requirement', arguments: { projectId: 'project-demo', repoPath: repo, client: 'codex', sessionId: 'session-mcp', text: 'Keep refresh token rotation documented.' } });
+    assert.strictEqual(response.result.structuredContent.projectId, 'project-demo');
+    assert.strictEqual(new ConversationStore({ layout, projectStore }).readEvents('project-demo').length, 1);
+    assert.strictEqual(fs.existsSync(layout.getProjectRequirementsPath('project-demo')), false, 'explicit MCP adapter must not create legacy requirements.jsonl');
+    assert.strictEqual(fs.readFileSync(layout.getProjectStatePath('project-demo'), 'utf8'), stateBefore, 'requirement tool must not trigger analysis or mutate state');
+    assert(!fs.existsSync(layout.getRuntimePath('staging')));
+
+    response = await client.request('tools/call', { name: 'project_knowledge_get', arguments: { projectId: 'project-demo', entry: '../settings.json' } });
+    assert.strictEqual(response.result.isError, true);
+    console.log('mcp-server-test PASS');
+  } finally {
+    client.child.stdin.end();
+    await new Promise(resolve => client.child.once('exit', resolve));
+  }
+})().catch(error => { console.error(error); process.exitCode = 1; }).finally(() => fs.rmSync(temp, { recursive: true, force: true }));

package/_site/_test/model-context-windows-test.js

@@ -0,0 +1,89 @@
+// Tests for model-context-windows: lookup table + resolution priority chain.
+//   profile.contextWindow (explicit override)
+//     → model name table (anthropic / minimax / glm / gpt / deepseek / qwen / gemini)
+//       → CLAUDE_CONTEXT_WINDOW env
+//         → 200000 fallback
+
+const { lookupContextWindow, resolveContextWindow } = require('../lib/model-context-windows');
+
+function assert(cond, msg) { if (!cond) throw new Error(msg); }
+
+(() => {
+  try {
+    // ---- lookupContextWindow: family prefix matching ----
+    assert(lookupContextWindow('claude-opus-4-7') === 200000, 'claude-opus-4-7 → 200000');
+    assert(lookupContextWindow('claude-sonnet-4-6') === 200000, 'claude-sonnet-4-6 → 200000');
+    assert(lookupContextWindow('claude-haiku-4-5') === 200000, 'claude-haiku-4-5 → 200000');
+    assert(lookupContextWindow('claude-3-5-sonnet-20241022') === 200000, 'claude-3-5 → 200000');
+
+    assert(lookupContextWindow('glm-5.2') === 1048576, 'glm-5.2 → 1M');
+    assert(lookupContextWindow('GLM-4.6') === 1048576, 'GLM-4.6 (uppercase) → 1M');
+    assert(lookupContextWindow('glm-4.5-air') === 128000, 'glm-4.5-air → 128000');
+    assert(lookupContextWindow('glm-4-plus') === 128000, 'glm-4-plus → 128000');
+
+    assert(lookupContextWindow('MiniMax-M3') === 1048576, 'MiniMax-M3 → 1M');
+    assert(lookupContextWindow('minimax-m2') === 1048576, 'minimax-m2 → 1M');
+
+    assert(lookupContextWindow('gpt-5-mini') === 200000, 'gpt-5-mini → 200000');
+    assert(lookupContextWindow('gpt-4o-2024-08-06') === 128000, 'gpt-4o → 128000');
+    assert(lookupContextWindow('gpt-4.1-2025-04-14') === 1047576, 'gpt-4.1 → 1047576');
+
+    assert(lookupContextWindow('deepseek-v3') === 128000, 'deepseek-v3 → 128000');
+    assert(lookupContextWindow('deepseek-r1') === 128000, 'deepseek-r1 → 128000');
+
+    assert(lookupContextWindow('qwen3-coder') === 131072, 'qwen3 → 131072');
+    assert(lookupContextWindow('gemini-2.5-pro') === 1048576, 'gemini-2.5 → 1M');
+
+    assert(lookupContextWindow('totally-unknown-model') === null, 'unknown → null');
+    assert(lookupContextWindow('') === null, 'empty → null');
+    assert(lookupContextWindow(null) === null, 'null → null');
+    assert(lookupContextWindow(undefined) === null, 'undefined → null');
+
+    // ---- resolveContextWindow: priority chain ----
+
+    // 1. profile.contextWindow wins over everything
+    assert(resolveContextWindow({ profileContextWindow: 500000, model: 'claude-opus-4' }) === 500000,
+      'explicit profileContextWindow must override table');
+
+    // 2. table wins when profile is empty
+    assert(resolveContextWindow({ model: 'glm-5.2' }) === 1048576,
+      'table hit should be used when profileContextWindow empty');
+
+    // 3. env wins when profile + table both miss
+    assert(resolveContextWindow({ model: 'unknown-model', env: { CLAUDE_CONTEXT_WINDOW: '99999' } }) === 99999,
+      'env should be used when table misses');
+
+    // 4. fallback (200000 default) when nothing matches
+    assert(resolveContextWindow({ model: 'unknown-model' }) === 200000,
+      'default fallback should be 200000');
+
+    // 5. profile.contextWindow = 0 / negative treated as unset
+    assert(resolveContextWindow({ profileContextWindow: 0, model: 'glm-5.2' }) === 1048576,
+      'profileContextWindow=0 should fall through to table');
+    assert(resolveContextWindow({ profileContextWindow: -1, model: 'glm-5.2' }) === 1048576,
+      'negative profileContextWindow should fall through to table');
+
+    // 6. non-finite profileContextWindow (NaN, string) ignored
+    assert(resolveContextWindow({ profileContextWindow: NaN, model: 'minimax-m3' }) === 1048576,
+      'NaN profileContextWindow should fall through');
+    assert(resolveContextWindow({ profileContextWindow: 'abc', model: 'minimax-m3' }) === 1048576,
+      'non-numeric string profileContextWindow should fall through');
+
+    // 7. custom fallback honored when nothing else matches
+    assert(resolveContextWindow({ model: 'unknown', fallback: 12345 }) === 12345,
+      'custom fallback should be respected');
+
+    // 8. no args at all → fallback
+    assert(resolveContextWindow() === 200000,
+      'no-args call should hit default fallback');
+
+    // 9. fractional context window floored
+    assert(resolveContextWindow({ profileContextWindow: 123456.789, model: 'x' }) === 123456,
+      'fractional contextWindow should be floored');
+
+    console.log('model-context-windows test passed');
+  } catch (e) {
+    console.error('model-context-windows test failed:', e.message);
+    process.exitCode = 1;
+  }
+})();