@sanqianx/project-knowledge 4.6.1

package/_site/_test/legacy-project-upgrade-e2e-test.js

@@ -0,0 +1,363 @@
+// _site/_test/legacy-project-upgrade-e2e-test.js
+//
+// Characterization harness for the v4.1.22 -> main migration path.
+// Builds a v4.1.22-shaped legacy data dir (projects.json, knowledge-store.json,
+// ai-profiles.json) plus a v1 managed post-commit hook in a real git repo,
+// then runs MigrationService + migrateManagedHook + CommitReconciler to prove
+// the legacy project continues to work without manual re-import.
+//
+// These tests are designed to fail under the current regressions and pass
+// after T01/T02/T03 fixes. They do NOT modify production code.
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const { StorageLayout } = require('../lib/storage-layout');
+const { MigrationService } = require('../lib/migration-service');
+const {
+  installHook,
+  readHookStatus,
+  migrateManagedHook,
+  LEGACY_HOOK_MARKER,
+  HOOK_MARKER,
+} = require('../lib/hook-manager');
+const { ProjectStore } = require('../lib/project-store');
+const { ProjectRegistryStore } = require('../lib/project-registry-store');
+const { Logger } = require('../lib/structured-logger');
+const { migrateManagedHooks } = require('../lib/server-app');
+
+function git(repo, args) {
+  const result = spawnSync('git', ['-C', repo, ...args], {
+    encoding: 'utf8',
+    windowsHide: true,
+    env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+  });
+  if (result.status !== 0) throw new Error(result.stderr || `git ${args.join(' ')} failed: ${result.status}`);
+  return String(result.stdout || '').trim();
+}
+
+function gitOrNull(repo, args) {
+  const result = spawnSync('git', ['-C', repo, ...args], {
+    encoding: 'utf8',
+    windowsHide: true,
+    env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+  });
+  return result.status === 0 ? String(result.stdout || '').trim() : null;
+}
+
+function makeRepo(repoPath) {
+  fs.mkdirSync(repoPath, { recursive: true });
+  git(repoPath, ['init', '-q', '-b', 'main']);
+  git(repoPath, ['config', 'user.email', 'legacy-e2e@example.local']);
+  git(repoPath, ['config', 'user.name', 'Legacy E2E']);
+  git(repoPath, ['config', 'commit.gpgsign', 'false']);
+  fs.writeFileSync(path.join(repoPath, 'README.md'), '# legacy\n');
+  git(repoPath, ['add', 'README.md']);
+  git(repoPath, ['commit', '-q', '-m', 'initial']);
+  return git(repoPath, ['rev-parse', 'HEAD']);
+}
+
+function makeLegacyFixture({ hookBody, includeHook = true } = {}) {
+  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-legacy-upgrade-e2e-'));
+  const repo = path.join(dataDir, 'repos', 'legacy-sample');
+  const kbPath = path.join(dataDir, 'knowledge', 'legacy-sample');
+  const initialSha = makeRepo(repo);
+  if (includeHook) {
+    const gitDir = git(repo, ['rev-parse', '--path-format=absolute', '--git-dir']);
+    const hooksDir = path.join(path.resolve(gitDir), 'hooks');
+    fs.mkdirSync(hooksDir, { recursive: true });
+    fs.writeFileSync(path.join(hooksDir, 'post-commit'), hookBody || (
+      `#!/bin/sh\n${LEGACY_HOOK_MARKER} — auto-installed by KB manager (legacy)\n` +
+      `node 'C:/legacy/site/_site/scripts/hook-trigger.js' --kb-root 'C:/legacy/site' \\\n` +
+      `  --repo "${repo.replace(/\\/g, '/')}" >/dev/null 2>&1 || true\nexit 0\n`
+    ), { mode: 0o755 });
+  }
+  fs.mkdirSync(kbPath, { recursive: true });
+  fs.writeFileSync(path.join(kbPath, 'README.md'), '# legacy knowledge\n');
+  fs.writeFileSync(path.join(dataDir, 'projects.json'), JSON.stringify({
+    'legacy-sample': {
+      schema: 'kb-project/v1',
+      displayName: 'Legacy Sample',
+      localPath: repo,
+      gitPath: repo,
+      kbPath,
+      trackingStartCommit: initialSha,
+      lastAnalyzedCommit: initialSha,
+      enabled: true,
+      aiProfileId: null,
+      knowledgeLanguage: 'zh-CN',
+    },
+  }, null, 2));
+  fs.writeFileSync(path.join(dataDir, 'knowledge-store.json'), JSON.stringify({
+    schema: 'knowledge-store/v1',
+    rootPath: path.join(dataDir, 'knowledge'),
+    configured: true,
+  }));
+  fs.writeFileSync(path.join(dataDir, 'ai-profiles.json'), JSON.stringify({
+    schema: 'ai-profiles/v1',
+    profiles: [
+      { id: 'primary', name: 'Primary', vendor: 'anthropic', model: 'claude-sonnet', enabled: true },
+    ],
+    defaultProfileId: 'primary',
+  }));
+  return { dataDir, repo, kbPath, initialSha };
+}
+
+async function run() {
+  const ROOT = path.resolve(__dirname, '..', '..');
+  const TRIGGER = path.join(ROOT, '_site', 'scripts', 'hook-trigger.js');
+
+  // ---- Case 1: legacy v1 hook must be upgraded by migrateManagedHook ----
+  {
+    const { dataDir, repo, kbPath, initialSha } = makeLegacyFixture();
+    const layout = new StorageLayout({ dataDir });
+    const migration = new MigrationService({ layout, legacyDataDir: dataDir });
+    const result = await migration.migrateIfNeeded({ migrationRunId: 'legacy-upgrade-v1' });
+    assert.strictEqual(result.ok, true, 'migration must succeed for a legacy fixture with v1 hook');
+    assert.strictEqual(result.completed, true, 'migration must complete');
+    const projectId = result.projectMap['legacy-sample'];
+    assert(projectId, 'migration must produce deterministic projectId mapping');
+    // Repo path preserved (not replaced with data-dir fallback)
+    const config = JSON.parse(fs.readFileSync(layout.getProjectConfigPath(projectId), 'utf8'));
+    assert.strictEqual(config.repoPath, path.resolve(repo), 'migrated repoPath must point at the real legacy repo, not a data-dir fallback');
+    assert.strictEqual(config.knowledgePath, path.resolve(kbPath), 'migrated knowledgePath must equal legacy kbPath');
+    assert.strictEqual(config.knowledgeLanguage, 'zh-CN', 'migrated knowledgeLanguage must be preserved');
+    const state = JSON.parse(fs.readFileSync(layout.getProjectStatePath(projectId), 'utf8'));
+    assert.strictEqual(state.trackingStartCommit, initialSha, 'trackingStartCommit must be preserved');
+    assert.strictEqual(state.lastAnalyzedCommit, initialSha, 'lastAnalyzedCommit must be preserved');
+    // Now invoke migrateManagedHook against the migrated repo: legacy v1 -> v2
+    const migrated = migrateManagedHook({ repoPath: repo, projectId, triggerScriptPath: TRIGGER });
+    assert.strictEqual(migrated.migrated, true, 'migrateManagedHook must report legacy->v2 migration');
+    assert.strictEqual(migrated.managedVersion, 2, 'managedVersion must advance to 2');
+    const status = readHookStatus({ repoPath: repo, projectId });
+    assert.strictEqual(status.kbManaged, true, 'after migration hook must be kb-managed');
+    assert.strictEqual(status.managedVersion, 2, 'after migration hook must be v2');
+    const hookBody = fs.readFileSync(status.hookPath, 'utf8');
+    assert(hookBody.includes(HOOK_MARKER), 'migrated hook body must carry the v2 marker');
+    assert(!hookBody.includes(LEGACY_HOOK_MARKER), 'migrated hook body must NOT carry the legacy v1 marker');
+    fs.rmSync(dataDir, { recursive: true, force: true });
+  }
+
+  // ---- Case 2: idempotent migration (second run) ----
+  {
+    const { dataDir } = makeLegacyFixture();
+    const layout = new StorageLayout({ dataDir });
+    const migration = new MigrationService({ layout, legacyDataDir: dataDir });
+    const first = await migration.migrateIfNeeded({ migrationRunId: 'legacy-idempotent' });
+    assert.strictEqual(first.completed, true);
+    const second = await migration.migrateIfNeeded();
+    assert.strictEqual(second.completed, true);
+    assert.strictEqual(second.migrated, false, 'second migration must be idempotent (no re-migration)');
+    fs.rmSync(dataDir, { recursive: true, force: true });
+  }
+
+  // ---- Case 3: missing legacy hook -> install + verify -> mark migrated ----
+  // T03 state-machine case 3: a missing hook must be installed and verified
+  // before migrationVersion=2 is written. The pre-fix bug (RC-02) was that
+  // migrateManagedHooks unconditionally wrote migrationVersion=2 even when
+  // migrateManagedHook returned { reason: 'missing' } with no install.
+  {
+    const { dataDir, repo } = makeLegacyFixture({ includeHook: false });
+    const layout = new StorageLayout({ dataDir });
+    const migration = new MigrationService({ layout, legacyDataDir: dataDir });
+    const result = await migration.migrateIfNeeded({ migrationRunId: 'legacy-missing-hook' });
+    assert.strictEqual(result.ok, true);
+    const projectId = result.projectMap['legacy-sample'];
+    const preStatus = readHookStatus({ repoPath: repo, projectId });
+    assert.strictEqual(preStatus.installed, false, 'fixture must not include a hook file');
+    const projectStore = new ProjectStore({ layout });
+    const registryStore = new ProjectRegistryStore({ layout });
+    await registryStore.initialize();
+    const logger = new Logger({ layout, settingsProvider: () => ({ levels: [] }), context: { component: 'legacy-upgrade-e2e' } });
+    const runtime = { registryStore, projectStore, logger, layout };
+    const hooks = await migrateManagedHooks(runtime);
+    const entry = hooks.find(item => item.projectId === projectId);
+    assert(entry, 'migrateManagedHooks must produce an entry for the migrated legacy project');
+    assert.strictEqual(entry.status, 'verified', 'missing hook must be installed+verified, not silently marked migrated');
+    assert.strictEqual(entry.reason, 'installed', 'a previously-missing hook reports reason=installed after migration');
+    const postStatus = readHookStatus({ repoPath: repo, projectId });
+    assert.strictEqual(postStatus.kbManaged, true, 'after migration the hook must be kb-managed');
+    assert.strictEqual(postStatus.managedVersion, 2, 'after migration the hook must be v2');
+    const finalState = projectStore.readState(projectId);
+    assert.strictEqual(finalState.hook.migrationVersion, 2, 'after successful install+verify, migrationVersion must advance to 2');
+    assert(finalState.hook.lastVerifiedAt && /^\d{4}-/.test(finalState.hook.lastVerifiedAt), 'after migration lastVerifiedAt must be a timestamp');
+    await logger.close();
+    fs.rmSync(dataDir, { recursive: true, force: true });
+  }
+
+  // ---- Case 3b: missing hook + install failure -> migrationVersion stays < 2 ----
+  // When the install step itself fails (e.g. the repo path is gone), the
+  // state machine must leave migrationVersion unchanged so the next startup
+  // can retry. The pre-fix bug advanced migrationVersion even when no hook
+  // was installed at all.
+  {
+    const { dataDir, repo } = makeLegacyFixture({ includeHook: false });
+    const layout = new StorageLayout({ dataDir });
+    const migration = new MigrationService({ layout, legacyDataDir: dataDir });
+    const result = await migration.migrateIfNeeded({ migrationRunId: 'legacy-missing-install-fail' });
+    assert.strictEqual(result.ok, true);
+    const projectId = result.projectMap['legacy-sample'];
+    // Remove the repo so installHook will fail (missing repo).
+    fs.rmSync(repo, { recursive: true, force: true });
+    const projectStore = new ProjectStore({ layout });
+    const registryStore = new ProjectRegistryStore({ layout });
+    await registryStore.initialize();
+    const logger = new Logger({ layout, settingsProvider: () => ({ levels: [] }), context: { component: 'legacy-upgrade-e2e' } });
+    const runtime = { registryStore, projectStore, logger, layout };
+    const hooks = await migrateManagedHooks(runtime);
+    // migrateManagedHooks skips projects whose repoPath is missing (the
+    // fs.existsSync check at the top of the loop). So the registry entry
+    // should not appear here. That is itself the correct behavior — we
+    // only assert it does NOT silently mark migrationVersion=2 when the
+    // repo is gone.
+    const entry = hooks.find(item => item.projectId === projectId);
+    if (entry) {
+      assert.notStrictEqual(entry.status, 'verified', 'a project whose repo is missing must not be marked verified');
+    }
+    const finalState = projectStore.readState(projectId);
+    assert.strictEqual(finalState.hook.migrationVersion < 2, true,
+      'RC-02 regression: a missing-repo project must not be marked migrationVersion=2');
+    await logger.close();
+    fs.rmSync(dataDir, { recursive: true, force: true });
+  }
+
+  // ---- Case 4: CHARACTERIZATION — third-party hook must not be silently overwritten ----
+  {
+    const { dataDir, repo } = makeLegacyFixture();
+    const gitDir = git(repo, ['rev-parse', '--path-format=absolute', '--git-dir']);
+    const hooksDir = path.join(path.resolve(gitDir), 'hooks');
+    fs.mkdirSync(hooksDir, { recursive: true });
+    const userHook = '#!/bin/sh\necho "user owned hook"\nexit 0\n';
+    fs.writeFileSync(path.join(hooksDir, 'post-commit'), userHook, { mode: 0o755 });
+    const layout = new StorageLayout({ dataDir });
+    const migration = new MigrationService({ layout, legacyDataDir: dataDir });
+    const result = await migration.migrateIfNeeded({ migrationRunId: 'legacy-third-party' });
+    assert.strictEqual(result.ok, true);
+    const projectId = result.projectMap['legacy-sample'];
+    let threw = false;
+    try {
+      migrateManagedHook({ repoPath: repo, projectId, triggerScriptPath: TRIGGER });
+    } catch (error) {
+      threw = error && (error.code === 'HOOK_CONFLICT' || /third-party|cannot be migrated/i.test(String(error.message || '')));
+    }
+    assert.strictEqual(threw, true, 'migrateManagedHook must reject a third-party post-commit hook');
+    const after = fs.readFileSync(path.join(hooksDir, 'post-commit'), 'utf8');
+    assert.strictEqual(after, userHook, 'third-party hook body must be untouched');
+    fs.rmSync(dataDir, { recursive: true, force: true });
+  }
+
+  // ---- Case 5: end-to-end commit on a migrated legacy project ----
+  // Validates that legacy knowledgePath/tracking survive a real commit cycle without manual re-import.
+  {
+    const { dataDir, repo, initialSha } = makeLegacyFixture();
+    const layout = new StorageLayout({ dataDir });
+    const migration = new MigrationService({ layout, legacyDataDir: dataDir });
+    const result = await migration.migrateIfNeeded({ migrationRunId: 'legacy-commit' });
+    assert.strictEqual(result.ok, true);
+    const projectId = result.projectMap['legacy-sample'];
+    // The fixture includes a v1 hook, so use migrateManagedHook which replaces
+    // legacy v1 with v2 using the T02 runtime contract.
+    const migrated = migrateManagedHook({ repoPath: repo, projectId, triggerScriptPath: TRIGGER });
+    assert.strictEqual(migrated.migrated, true, 'migrateManagedHook must report v1 -> v2');
+    assert.strictEqual(migrated.managedVersion, 2, 'migrated managedVersion must be 2');
+    // New commit in the legacy repo
+    fs.writeFileSync(path.join(repo, 'change.txt'), 'second\n');
+    git(repo, ['add', 'change.txt']);
+    git(repo, ['commit', '-q', '-m', 'second']);
+    const newHead = git(repo, ['rev-parse', 'HEAD']);
+    assert.notStrictEqual(newHead, initialSha, 'fixture must create a second commit');
+    // Verify hook is present and v2
+    const status = readHookStatus({ repoPath: repo, projectId });
+    assert.strictEqual(status.kbManaged, true);
+    assert.strictEqual(status.managedVersion, 2);
+    fs.rmSync(dataDir, { recursive: true, force: true });
+  }
+
+  // ---- Case 6: second startup after successful migration -> no duplicate rewrite ----
+  // The post-T03 contract: once a project is verified migrated, a subsequent
+  // startup must not touch the hook file or rewrite migrationVersion.
+  {
+    const { dataDir, repo } = makeLegacyFixture({ includeHook: false });
+    const layout = new StorageLayout({ dataDir });
+    const migration = new MigrationService({ layout, legacyDataDir: dataDir });
+    const result = await migration.migrateIfNeeded({ migrationRunId: 'legacy-second-startup' });
+    assert.strictEqual(result.ok, true);
+    const projectId = result.projectMap['legacy-sample'];
+    const projectStore = new ProjectStore({ layout });
+    const registryStore = new ProjectRegistryStore({ layout });
+    await registryStore.initialize();
+    const logger = new Logger({ layout, settingsProvider: () => ({ levels: [] }), context: { component: 'legacy-upgrade-e2e' } });
+    const runtime = { registryStore, projectStore, logger, layout };
+    // First startup
+    const firstPass = await migrateManagedHooks(runtime);
+    assert(firstPass.length > 0, `migrateManagedHooks must produce at least one entry; got ${JSON.stringify(firstPass)}`);
+    const firstEntry = firstPass.find(item => item.projectId === projectId);
+    assert(firstEntry, `first pass must include the migrated project; got: ${JSON.stringify(firstPass.map(p => p.projectId))}`);
+    assert.strictEqual(firstEntry.status, 'verified');
+    assert.strictEqual(firstEntry.reason, 'installed');
+    const hookPath = readHookStatus({ repoPath: repo, projectId }).hookPath;
+    const firstMtime = fs.statSync(hookPath).mtimeMs;
+    const firstBody = fs.readFileSync(hookPath, 'utf8');
+    const firstState = projectStore.readState(projectId);
+    const firstVerifiedAt = firstState.hook.lastVerifiedAt;
+    // Wait briefly so a rewrite would change mtime
+    await new Promise(resolve => setTimeout(resolve, 20));
+    // Second startup
+    const secondPass = await migrateManagedHooks(runtime);
+    const secondEntry = secondPass.find(item => item.projectId === projectId);
+    assert.strictEqual(secondEntry.status, 'verified');
+    assert.strictEqual(secondEntry.reason, 'already-migrated', 'second startup must report reason=already-migrated without rewriting');
+    assert.strictEqual(fs.readFileSync(hookPath, 'utf8'), firstBody, 'hook body must be untouched on second startup');
+    assert.strictEqual(fs.statSync(hookPath).mtimeMs, firstMtime, 'hook mtime must be unchanged on second startup');
+    const secondState = projectStore.readState(projectId);
+    assert.strictEqual(secondState.hook.lastVerifiedAt, firstVerifiedAt, 'lastVerifiedAt must not be re-stamped on idempotent pass');
+    await logger.close();
+    fs.rmSync(dataDir, { recursive: true, force: true });
+  }
+
+  // ---- Case 7: third-party hook -> migration incomplete (T03 case 4) ----
+  // Verifies the migrateManagedHooks state machine reports conflict without
+  // overwriting the user's hook.
+  {
+    const { dataDir, repo } = makeLegacyFixture({ includeHook: false });
+    const gitDir = git(repo, ['rev-parse', '--path-format=absolute', '--git-dir']);
+    const hooksDir = path.join(path.resolve(gitDir), 'hooks');
+    fs.mkdirSync(hooksDir, { recursive: true });
+    const userHook = '#!/bin/sh\necho "third-party"\nexit 0\n';
+    fs.writeFileSync(path.join(hooksDir, 'post-commit'), userHook, { mode: 0o755 });
+    const layout = new StorageLayout({ dataDir });
+    const migration = new MigrationService({ layout, legacyDataDir: dataDir });
+    const result = await migration.migrateIfNeeded({ migrationRunId: 'legacy-third-party-state' });
+    assert.strictEqual(result.ok, true);
+    const projectId = result.projectMap['legacy-sample'];
+    const projectStore = new ProjectStore({ layout });
+    const registryStore = new ProjectRegistryStore({ layout });
+    await registryStore.initialize();
+    const logger = new Logger({ layout, settingsProvider: () => ({ levels: [] }), context: { component: 'legacy-upgrade-e2e' } });
+    const runtime = { registryStore, projectStore, logger, layout };
+    const pass = await migrateManagedHooks(runtime);
+    const entry = pass.find(item => item.projectId === projectId);
+    assert(entry, 'migrateManagedHooks must produce an entry for the third-party-hook project');
+    assert.strictEqual(entry.status, 'conflict', 'third-party hook must be reported as conflict, not verified');
+    assert.strictEqual(entry.reason, 'third-party');
+    const finalState = projectStore.readState(projectId);
+    assert.strictEqual(finalState.hook.migrationVersion < 2, true,
+      'third-party hook must not be marked migrationVersion=2');
+    assert(finalState.hook.lastConflict && finalState.hook.lastConflict.code === 'HOOK_CONFLICT',
+      'third-party conflict must be persisted in lastConflict for UI consumption');
+    assert.strictEqual(fs.readFileSync(path.join(hooksDir, 'post-commit'), 'utf8'), userHook,
+      'third-party hook body must remain untouched');
+    await logger.close();
+    fs.rmSync(dataDir, { recursive: true, force: true });
+  }
+
+  console.log('legacy-project-upgrade-e2e-test PASS');
+}
+
+run().catch(error => {
+  console.error(error.stack || error.message);
+  process.exit(1);
+});

package/_site/_test/legacy-routes-removed-test.js

@@ -0,0 +1,47 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnServer } = require('./helpers/spawn-server');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const PORT = 7833;
+const BASE = `http://127.0.0.1:${PORT}`;
+const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pkb-routes-v2-'));
+
+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 source = `${fs.readFileSync(path.join(ROOT, '_site', 'server.js'), 'utf8')}\n${fs.readFileSync(path.join(ROOT, '_site', 'lib', 'server-app.js'), 'utf8')}`;
+  for (const removedSymbol of ['automation/simulate', 'automation/init', 'hook-install', 'hook-uninstall', 'dispatchProjectInit', 'DEFAULT_INIT_PROMPT_TEMPLATE', 'renderProjectInitPrompt', '/api/raw']) {
+    assert(!source.includes(removedSymbol), `removed production symbol remains: ${removedSymbol}`);
+  }
+
+  const spawned = spawnServer({ root: ROOT, port: PORT, dataDir, tag: 'routes-v2', extraEnv: { KB_SKIP_MIGRATION: '1' } });
+  try {
+    await waitForServer();
+    const routes = [
+      ['PUT', '/api/projects'],
+      ['POST', '/api/projects/project-example/init'],
+      ['POST', '/api/projects/project-example/automation/simulate'],
+      ['POST', '/api/projects/project-example/automation/init'],
+      ['GET', '/api/projects/project-example/hook-status'],
+      ['POST', '/api/projects/project-example/hook-install'],
+      ['POST', '/api/projects/project-example/hook-uninstall'],
+      ['GET', '/api/raw?path=README.md'],
+    ];
+    for (const [method, pathname] of routes) {
+      const response = await fetch(`${BASE}${pathname}`, { method });
+      assert.strictEqual(response.status, 404, `${method} ${pathname} should be removed`);
+    }
+    console.log('legacy-routes-removed-test PASS');
+  } finally {
+    await spawned.cleanup();
+  }
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/legacy-workbench-exclusion-test.js

@@ -0,0 +1,92 @@
+// Run: node _site/_test/legacy-workbench-exclusion-test.js
+//
+// T17 / GATE LEGACY-001: old embedded Workbench pairs are excluded from
+// Development Conversation presentation and new commit binding; genuine
+// explicit MCP requirements survive; immutable snapshots and JSONL lines are
+// never rewritten.
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { StorageLayout } = require('../lib/storage-layout');
+const { ProjectStore } = require('../lib/project-store');
+const { ConversationStore } = require('../lib/conversation-store');
+const { CommitConversationBinder } = require('../lib/commit-conversation-binder');
+const { computeConversationExclusions, readDevelopmentEvents } = require('../lib/conversation-exclusions');
+
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), `kb-legacy-exclusion-${process.pid}-`));
+const layout = new StorageLayout({ dataDir: path.join(temp, 'data') });
+const projects = new ProjectStore({ layout });
+const store = new ConversationStore({ layout, projectStore: projects, logger: null });
+const projectId = 'project-legacy';
+
+const repoIdentity = { commonDir: path.join(temp, 'repo', '.git') };
+
+async function append(input) {
+  await store.appendEvent(projectId, {
+    source: 'claude-code',
+    sessionId: 'legacy-session',
+    projectPath: path.join(temp, 'repo'),
+    repoIdentity,
+    branch: 'main',
+    capturedAt: '2026-08-01T00:00:00.000Z',
+    ...input,
+  });
+}
+
+(async () => {
+  await projects.create(projectId, {
+    displayName: 'Legacy', storageName: 'legacy',
+    repoPath: path.join(temp, 'repo'), knowledgePath: path.join(temp, 'knowledge'),
+    repoIdentity,
+  }, { conversationBaselineCursor: 0 });
+
+  // Old embedded Workbench pair (explicit-REQ1 + embedded-assistant-REQ1).
+  await append({ eventId: 'explicit-REQ1', sequence: 1, eventType: 'user_prompt', role: 'user', content: 'Workbench prompt', turnId: 'turn-embed-1', identityConfidence: 'high' });
+  await append({ eventId: 'embedded-assistant-REQ1', sequence: 2, eventType: 'assistant_response', role: 'assistant', content: 'Workbench reply', turnId: 'turn-embed-1', rawEventType: 'embedded-claude-result', identityConfidence: 'high' });
+  // Genuine explicit MCP requirement NOT paired with an embedded assistant.
+  await append({ eventId: 'explicit-REQ2', sequence: 3, eventType: 'user_prompt', role: 'user', content: 'Genuine MCP requirement', turnId: 'turn-explicit-2', identityConfidence: 'explicit', explicitCommitSha: 'f'.repeat(40) });
+  // Modern bridge-projected event.
+  await append({ eventId: 'evt-bridge-1', sequence: 4, eventType: 'user_prompt', role: 'user', content: 'Modern bridge event', turnId: 'turn-bridge', identityConfidence: 'exact' });
+
+  const eventsRaw = store.readEvents(projectId);
+  assert.strictEqual(eventsRaw.length, 4, 'raw JSONL lines are never deleted');
+
+  const manifest = computeConversationExclusions(projectId, eventsRaw);
+  assert.deepStrictEqual(manifest.excludedEventIds, ['embedded-assistant-REQ1', 'explicit-REQ1'], 'only the embedded pair is excluded');
+
+  const development = readDevelopmentEvents(store, projectId);
+  assert.deepStrictEqual(development.map(event => event.eventId), ['explicit-REQ2', 'evt-bridge-1'], 'genuine explicit + bridge events survive');
+  assert.strictEqual(development.some(event => event.content === 'Workbench prompt'), false);
+  assert.strictEqual(development.some(event => event.content === 'Workbench reply'), false);
+
+  // Manifest persisted for audit; JSONL untouched.
+  const manifestFile = path.join(layout.getProjectMetadataDir(projectId), 'conversation-exclusions.json');
+  assert.ok(fs.existsSync(manifestFile), 'exclusion manifest is persisted');
+  assert.strictEqual(JSON.parse(fs.readFileSync(manifestFile, 'utf8')).schema, 'conversation-exclusions/v1');
+  assert.strictEqual(store.readEvents(projectId).length, 4, 'raw store still holds every historical line');
+
+  // New commit binding excludes the legacy pair.
+  const binder = new CommitConversationBinder({ layout, projectStore: projects, conversationStore: store });
+  const commitSha = 'a'.repeat(40);
+  store.writeBoundary(projectId, {
+    repoIdentity, commitSha, parentShas: [], branch: 'main', committedAt: '2026-08-02T00:00:00.000Z',
+    bridgeCursorAtCommit: 10, journalSequence: 10, openTurnIdsAtCommit: [], operationId: 'op-legacy',
+  });
+  const snapshot = await binder.bind({ projectId, commitSha });
+  assert.ok(!JSON.stringify(snapshot).includes('Workbench prompt'), 'legacy embedded pair never binds to a new commit');
+  assert.ok(!JSON.stringify(snapshot).includes('embedded-claude-result'));
+
+  // An old frozen snapshot written before the migration stays byte-identical.
+  const frozenPath = layout.getProjectCommitConversationPath(projectId, commitSha);
+  const before = fs.readFileSync(frozenPath, 'utf8');
+  const rebound = await binder.bind({ projectId, commitSha });
+  assert.strictEqual(rebound.snapshotHash, snapshot.snapshotHash, 'immutable snapshot untouched by exclusion');
+  assert.strictEqual(fs.readFileSync(frozenPath, 'utf8'), before);
+
+  console.log('legacy-workbench-exclusion-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+});

package/_site/_test/log-redaction-test.js

@@ -0,0 +1,58 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { StorageLayout } = require('../lib/storage-layout');
+const { Logger, LogRepository, redactValue, serializeError } = require('../lib/structured-logger');
+
+(async () => {
+  const secret = 'sk-secret-123456';
+  const value = redactValue({
+    apiKey: secret,
+    headers: { authorization: 'Bearer ' + secret },
+    url: 'https://user:' + secret + '@example.invalid/path?token=' + secret,
+    nested: [{ clientSecret: secret }, { safe: 'visible' }],
+  }, { secrets: [secret] });
+  const text = JSON.stringify(value);
+  assert(!text.includes(secret));
+  assert(text.includes('visible'));
+
+  const cause = Object.assign(new Error('cause ' + secret), { code: 'ECAUSE' });
+  const error = Object.assign(new Error('Bearer ' + secret), { code: 'ETEST', cause });
+  const serialized = JSON.stringify(serializeError(error, { secrets: [secret] }));
+  assert(!serialized.includes(secret));
+  assert(serialized.includes('ETEST'));
+  assert(serialized.includes('ECAUSE'));
+
+  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-dynamic-redaction-'));
+  try {
+    const layout = new StorageLayout({ dataDir });
+    let currentSecret = 'dynamic-secret-one';
+    const settings = { levels: ['info', 'error'], retentionDays: 365, maxTotalSizeMB: 10 };
+    const secretsProvider = () => [currentSecret];
+    const logger = new Logger({ layout, settingsProvider: () => settings, secretsProvider });
+    await logger.info('secret.first', 'first ' + currentSecret, { context: { echoed: currentSecret } });
+    currentSecret = 'dynamic-secret-two';
+    await logger.error('secret.second', 'second ' + currentSecret, { error: new Error('failure ' + currentSecret) });
+    await logger.close();
+
+    const repository = new LogRepository({ layout, settingsProvider: () => settings, secretsProvider });
+    const page = repository.query({ from: '2000-01-01', to: '2999-12-31' });
+    const queried = JSON.stringify(page);
+    assert(!queried.includes(currentSecret), 'current configured secret must be redacted during query');
+    assert(!queried.includes('dynamic-secret-one'), 'write-time configured secret must be redacted before persistence');
+
+    const exportPath = path.join(dataDir, 'export.jsonl');
+    repository.exportToFile(exportPath, { from: '2000-01-01', to: '2999-12-31' });
+    const exported = fs.readFileSync(exportPath, 'utf8');
+    assert(!exported.includes('dynamic-secret-one'));
+    assert(!exported.includes('dynamic-secret-two'));
+  } finally {
+    fs.rmSync(dataDir, { recursive: true, force: true });
+  }
+
+  console.log('log-redaction-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+});

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

@@ -0,0 +1,89 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { StorageLayout } = require('../lib/storage-layout');
+const { Logger, LogRepository, localDay, normalizeRecord } = require('../lib/structured-logger');
+
+function line(entry) {
+  return `${JSON.stringify(normalizeRecord(entry))}\r\n`;
+}
+
+(async () => {
+  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-log-repository-'));
+  const layout = new StorageLayout({ dataDir });
+  const settings = { levels: ['trace', 'debug', 'info', 'warn', 'error', 'fatal'] };
+  const logger = new Logger({ layout, settingsProvider: () => settings });
+  await logger.info('app.started', 'Started', { component: 'server', operationId: 'op-a' });
+  await logger.info('app.completed', 'Completed', { component: 'server', operationId: 'op-a', durationMs: 12 });
+  await logger.warn('project.deleted', 'Deleted project snapshot', { component: 'lifecycle', projectId: 'project-a', projectDisplayName: 'A', projectDeleted: true });
+  await logger.error('commit.analysis.failed', 'Failed', { component: 'commit-reconciler', projectId: 'project-a', operationId: 'op-b', commitSha: 'deadbeef', error: Object.assign(new Error('failure'), { code: 'ETEST' }) });
+  await logger.close();
+
+  const repository = new LogRepository({ layout });
+  const result = repository.query({ levels: ['error'], projectId: 'project-a', component: 'commit-reconciler', commitSha: 'deadbeef' });
+  assert.strictEqual(result.entries.length, 1);
+  assert.strictEqual(result.entries[0].operationId, 'op-b');
+  assert.strictEqual(result.entries[0].error.code, 'ETEST');
+  assert.strictEqual(result.pageSize, 500, 'today query must default to 500 records');
+  assert.strictEqual(repository.query({ pageSize: 999999 }).pageSize, 5000, 'display limit must be capped at 5000');
+  assert.strictEqual(repository.findOrphanedOperations().length, 0);
+
+  await logger.info('migration.started', 'Migration started', { component: 'migration', operationId: 'op-orphan' });
+  await logger.close();
+  assert.strictEqual(repository.findOrphanedOperations().length, 1);
+
+  const legacyRoot = layout.getLogPath('app');
+  fs.mkdirSync(legacyRoot, { recursive: true });
+  fs.writeFileSync(path.join(legacyRoot, '2020-01-01.log'), `${JSON.stringify({ ts: '2020-01-01T00:00:00.000Z', level: 'info', source: 'legacy', event: 'legacy.event', message: 'old' })}\n`);
+  assert.strictEqual(repository.query({ from: '2019-01-01', to: '2021-01-01', event: 'legacy.event' }).entries.length, 1, 'legacy app/hooks logs remain read-only query sources');
+
+  const date = localDay();
+  const mergeA = path.join(layout.getLogPath('project', 'merge-a'), `${date}.jsonl`);
+  const mergeB = path.join(layout.getLogPath('project', 'merge-b'), `${date}.jsonl`);
+  fs.mkdirSync(path.dirname(mergeA), { recursive: true });
+  fs.mkdirSync(path.dirname(mergeB), { recursive: true });
+  const longMessage = `long-${'界'.repeat(70000)}`;
+  const longRecord = { ...normalizeRecord({ id: 'a-1', ts: `${date}T01:00:00.000Z`, level: 'info', event: 'merge.a1', message: 'placeholder', projectId: 'merge-a' }), message: longMessage };
+  fs.writeFileSync(mergeA,
+    `${JSON.stringify(longRecord)}\r\n`
+    + line({ id: 'a-2', ts: `${date}T03:00:00.000Z`, level: 'warn', event: 'merge.a2', message: 'newer a', projectId: 'merge-a' })
+    + '{bad-tail',
+    'utf8');
+  fs.writeFileSync(mergeB,
+    line({ id: 'b-1', ts: `${date}T02:00:00.000Z`, level: 'error', event: 'merge.b1', message: 'middle b', projectId: 'merge-b' }),
+    'utf8');
+
+  const originalReadFileSync = fs.readFileSync;
+  fs.readFileSync = function guardedRead(filePath, ...args) {
+    if (typeof filePath === 'string' && filePath.startsWith(path.join(dataDir, 'logs')) && /\.(?:jsonl|log)$/.test(filePath)) {
+      throw new Error('LogRepository must not read an entire log file');
+    }
+    return originalReadFileSync.call(this, filePath, ...args);
+  };
+  let merged;
+  try {
+    merged = repository.query({ event: '', q: 'merge.', pageSize: 3 });
+  } finally {
+    fs.readFileSync = originalReadFileSync;
+  }
+  assert.deepStrictEqual(merged.entries.map(entry => entry.id), ['a-2', 'b-1', 'a-1'], 'all-project query must k-way merge by timestamp and skip malformed tail data');
+  const long = repository.query({ projectId: 'merge-a', event: 'merge.a1' });
+  assert.strictEqual(long.entries.length, 1);
+  assert(long.entries[0].message.startsWith(`long-${'界'.repeat(100)}`), 'reverse chunk reader must parse lines larger than one chunk');
+  assert(long.entries[0].message.includes('[truncated:'), 'public query must still apply field size bounds');
+
+  const cursorPage = repository.query({ q: 'merge.', pageSize: 1 });
+  assert(cursorPage.nextCursor);
+  fs.unlinkSync(mergeB);
+  assert.throws(
+    () => repository.query({ q: 'merge.', pageSize: 1, cursor: cursorPage.nextCursor }),
+    error => error.code === 'LOG_CURSOR_EXPIRED' && error.retryable === true,
+    'manually deleted cursor source must return a typed restart error',
+  );
+
+  console.log('logging-api-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+});