@sanqianx/project-knowledge 4.6.1

package/_site/_test/commit-evidence-test.js

@@ -0,0 +1,110 @@
+// Run: node _site/_test/commit-evidence-test.js
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { CommitScanner, TrustedGitReader, EMPTY_TREE_SHA, sha256 } = require('../lib/scanner');
+
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), `kb-commit-evidence-${process.pid}-`));
+const repo = path.join(temp, 'repo');
+
+function git(args) {
+  const result = spawnSync('git', ['-C', repo, ...args], { encoding: 'utf8', windowsHide: true, maxBuffer: 16 * 1024 * 1024 });
+  if (result.status !== 0) throw new Error(result.stderr || `git ${args.join(' ')} failed`);
+  return String(result.stdout || '').trim();
+}
+
+function gitRaw(args) {
+  const result = spawnSync('git', ['-C', repo, ...args], { encoding: 'utf8', windowsHide: true, maxBuffer: 16 * 1024 * 1024 });
+  if (result.status !== 0) throw new Error(result.stderr || `git ${args.join(' ')} failed`);
+  return String(result.stdout || '');
+}
+
+function commitFile(name, content, message) {
+  fs.mkdirSync(path.dirname(path.join(repo, name)), { recursive: true });
+  fs.writeFileSync(path.join(repo, name), content);
+  git(['add', name]);
+  git(['commit', '-m', message]);
+  return git(['rev-parse', 'HEAD']);
+}
+
+(async () => {
+  fs.mkdirSync(repo, { recursive: true });
+  git(['init', '--initial-branch=main']);
+  git(['config', 'user.email', 'evidence@example.test']);
+  git(['config', 'user.name', 'Evidence Test']);
+  const rootCommit = commitFile('src/root.txt', 'root\n', 'root commit');
+  const binaryCommit = commitFile('assets/sample.bin', Buffer.from([0, 1, 2, 3, 255]), 'add binary');
+
+  git(['checkout', '-b', 'feature']);
+  const featureCommit = commitFile('src/feature.txt', 'feature\n', 'feature side');
+  git(['checkout', 'main']);
+  const mainCommit = commitFile('src/main.txt', 'main\n', 'main side');
+  git(['merge', '--no-ff', 'feature', '-m', 'merge feature']);
+  const mergeCommit = git(['rev-parse', 'HEAD']);
+
+  const scanner = new CommitScanner({ batchSize: 2 });
+  const firstBatch = await scanner.scan({ repoPath: repo }, {
+    trackingMode: 'normal', trackingStartCommit: rootCommit, lastAnalyzedCommit: null,
+  });
+  assert.strictEqual(firstBatch.status, 'ok');
+  assert.strictEqual(firstBatch.commits.length, 2, 'batch limit should return a bounded first page');
+  assert(firstBatch.continuation && firstBatch.continuation.remaining === 2, 'continuation must expose remaining work');
+  const all = await new TrustedGitReader().listCommits(repo, rootCommit, mergeCommit);
+  assert.deepStrictEqual(all, [binaryCommit, mainCommit, featureCommit, mergeCommit], 'reverse topo order must include both branch commits and the merge commit');
+
+  const rootEvidence = await scanner.collectEvidence({ repoPath: repo }, rootCommit, { branch: 'main' });
+  assert.strictEqual(rootEvidence.patchMode, 'root-empty-tree');
+  assert.strictEqual(rootEvidence.patchBase, EMPTY_TREE_SHA);
+  assert(rootEvidence.patch.includes('src/root.txt'), 'root evidence must contain a real empty-tree patch');
+
+  const binaryEvidence = await scanner.collectEvidence({ repoPath: repo }, binaryCommit, { branch: 'main' });
+  assert(binaryEvidence.files.some(file => file.path === 'assets/sample.bin' && file.binary), 'name-status manifest should identify binary files');
+  assert(binaryEvidence.patch.includes('GIT binary patch'), 'binary patch evidence should be preserved');
+
+  const mergeEvidence = await scanner.collectEvidence({ repoPath: repo }, mergeCommit, { branch: 'main' });
+  assert.strictEqual(mergeEvidence.parents.length, 2, 'merge metadata should include every parent');
+  assert.strictEqual(mergeEvidence.patchMode, 'merge-first-parent');
+  assert.strictEqual(mergeEvidence.patchBase, mainCommit, 'merge patch must compare against the first parent');
+  assert(mergeEvidence.patch.includes('src/feature.txt'), 'first-parent merge patch should show the introduced feature side');
+
+  git(['mv', 'src/root.txt', 'src/renamed.txt']);
+  git(['commit', '-m', 'rename root evidence']);
+  const renameCommit = git(['rev-parse', 'HEAD']);
+  const renameEvidence = await scanner.collectEvidence({ repoPath: repo }, renameCommit, { branch: 'main' });
+  assert(renameEvidence.files.some(file => file.oldPath === 'src/root.txt' && file.path === 'src/renamed.txt'), 'rename evidence must retain old and new paths');
+
+  const largeContent = Array.from({ length: 42000 }, (_, index) => `${String(index).padStart(6, '0')} ${'exact-evidence-'.repeat(5)}\n`).join('');
+  const largeCommit = commitFile('src/large.txt', largeContent, 'large exact evidence');
+  const evidenceRoot = path.join(temp, 'run', 'input', 'evidence');
+  const largeReader = new TrustedGitReader({ maxPatchBytes: 2 * 1024 * 1024, maxChunkBytes: 128 * 1024 });
+  const large = await largeReader.collectEvidence(repo, largeCommit, { branch: 'main', evidenceRoot });
+  assert(large.patchBytes > 2 * 1024 * 1024, 'fixture must cross the production inline threshold');
+  assert.strictEqual(large.patch, null, 'large patch should be referenced by exact chunks instead of prompt inline text');
+  assert.strictEqual(large.patchChunked, true);
+  assert.strictEqual(large.patchOmitted, false, 'exact chunk evidence must not be represented as omitted');
+  assert(large.evidenceBundle.chunkCount > 1, 'large patch should be split into ordered chunks');
+  const manifest = largeReader.verifyEvidence(large);
+  assert.deepStrictEqual(manifest.chunks.map(chunk => chunk.sequence), manifest.chunks.map((_, index) => index + 1));
+  assert(manifest.chunks.every(chunk => chunk.sha256.startsWith('sha256:') && chunk.bytes > 0 && chunk.sourcePaths.includes('src/large.txt')));
+  const reconstructed = manifest.chunks.map(chunk => fs.readFileSync(path.join(evidenceRoot, ...chunk.path.split('/')))).join('');
+  const exactGitPatch = gitRaw(['diff', '--no-ext-diff', '--binary', '--find-renames', '--unified=3', renameCommit, largeCommit]);
+  assert.strictEqual(Buffer.byteLength(reconstructed), Buffer.byteLength(exactGitPatch));
+  assert.strictEqual(sha256(reconstructed), large.patchHash, 'ordered chunks must exactly reconstruct the full Git diff hash');
+
+  const corruptPath = path.join(evidenceRoot, ...manifest.chunks[0].path.split('/'));
+  fs.appendFileSync(corruptPath, 'corrupt');
+  assert.throws(() => largeReader.verifyEvidence(large), error => error.code === 'EVIDENCE_INTEGRITY_FAILED', 'corrupt chunks must fail with a typed evidence error');
+
+  const missingRootReader = new TrustedGitReader({ maxPatchBytes: 8 });
+  await assert.rejects(missingRootReader.collectEvidence(repo, mergeCommit, { branch: 'main' }), error => error.code === 'EVIDENCE_INTEGRITY_FAILED');
+
+  console.log('commit-evidence-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+}).finally(() => {
+  fs.rmSync(temp, { recursive: true, force: true });
+});

package/_site/_test/context-pack-test.js

@@ -0,0 +1,198 @@
+// TASK-006: Context pack builder test
+// Run: node _site/_test/context-pack-test.js
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn } = require('child_process');
+const { spawnServer } = require('./helpers/spawn-server');
+const { makeRepo, git } = require('./fixtures/make-git-repos');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const SERVER = path.join(ROOT, '_site', 'server.js');
+// Pre-create a temp data dir and seed it BEFORE requiring any lib modules
+// that capture getDataDir() at module load. Both the test process and
+// the spawned server will use this dir.
+const DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), `kb-data-context-pack-${process.pid}-`));
+process.env.KB_DATA_DIR = DATA_DIR;
+require('../lib/data-dir')._resetCache();
+try { fs.copyFileSync(path.join(ROOT, 'claude-prompts.json'), path.join(DATA_DIR, 'claude-prompts.json')); } catch {}
+
+const { buildContextPack, isSafePath, PACKAGE_CONFIG_FILES } = require('../lib/context-pack-builder');
+let PROJECTS_JSON = path.join(DATA_DIR, 'projects.json');
+const PORT = process.env.KB_CTX_TEST_PORT || '7796';
+const BASE_URL = `http://127.0.0.1:${PORT}`;
+const TEMP_SLUG = 'task-006-temp';
+
+function assert(cond, msg) { if (!cond) throw new Error(msg); }
+
+async function waitForServer() {
+  const deadline = Date.now() + 15000;
+  let lastError;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(`${BASE_URL}/api/state`);
+      if (res.ok) return;
+      lastError = new Error(`HTTP ${res.status}`);
+    } catch (e) { lastError = e; }
+    await new Promise(r => setTimeout(r, 250));
+  }
+  throw lastError || new Error('server did not start');
+}
+
+async function json(method, url, body) {
+  const res = await fetch(`${BASE_URL}${url}`, {
+    method,
+    headers: body ? { 'Content-Type': 'application/json' } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  let data = {};
+  if (text) { try { data = JSON.parse(text); } catch { data = { raw: text }; } }
+  return { res, data };
+}
+
+async function cleanup() {
+  // The whole test data directory is isolated and removed after the server exits.
+}
+
+(async () => {
+  // 1. Path safety
+  assert(isSafePath('/tmp/proj', 'a/b.md'), 'safe path should pass');
+  assert(!isSafePath('/tmp/proj', '../escape.md'), 'parent traversal should fail');
+  assert(!isSafePath('/tmp/proj', '/etc/passwd'), 'absolute outside should fail');
+  // Sibling that is not a sub-path: resolve it relative to the project root and check.
+  const siblingResolved = require('path').resolve('/tmp/proj', '../proj-other/x.md');
+  assert(!siblingResolved.startsWith('/tmp/proj/') && siblingResolved !== '/tmp/proj',
+    'sibling-of-project should not pass when constructed as a traversal');
+  assert(Array.isArray(PACKAGE_CONFIG_FILES) && PACKAGE_CONFIG_FILES.includes('package.json'), 'package config list ok');
+
+  // 2. Unit test: build a context pack for a feature-commit fixture
+  const repo = makeRepo({ kind: 'feature-commit' });
+  const kbBase = path.join(DATA_DIR, 'projects', TEMP_SLUG);
+  fs.mkdirSync(kbBase, { recursive: true });
+  // Lay down final minimal KB structure with a module doc that references a changed file.
+  fs.mkdirSync(path.join(kbBase, 'modules'), { recursive: true });
+  fs.mkdirSync(path.join(kbBase, 'changes'), { recursive: true });
+  fs.writeFileSync(path.join(kbBase, 'GOAL.md'), '# Goal — test\n\nGoal text for tests.\n');
+  fs.writeFileSync(path.join(kbBase, 'ARCHITECTURE.md'), '# Analysis — test\n');
+  fs.writeFileSync(path.join(kbBase, 'modules', 'feature.md'), 'See `src/feature.ts` for the implementation.\n');
+  fs.writeFileSync(path.join(kbBase, 'README.md'), '# Project — test\n');
+  // package.json lives in the source repo (the fixture already has a src/, but no package.json)
+  fs.writeFileSync(path.join(repo.path, 'package.json'), '{"name":"fixture"}');
+
+  const commits = repo.commits.slice().reverse(); // chronological
+  const pack = await buildContextPack({
+    project: {
+      slug: TEMP_SLUG,
+      kbPath: kbBase,
+      gitPath: repo.path,
+      localPath: repo.path,
+    },
+    runId: 'run-unit-1',
+    trigger: 'commits',
+    commits,
+  });
+
+  assert(pack.schema === 'context-pack/v1', 'pack schema should be v1');
+  assert(pack.runId === 'run-unit-1', 'runId should be honored');
+  assert(pack.trigger === 'commits', 'trigger should be commits');
+  assert(pack.commitCount === commits.length, 'commitCount should match');
+  assert(pack.range, 'range should be set');
+
+  // Required entries
+  const goalEntry = pack.entries.find(e => e.path === 'GOAL.md');
+  assert(goalEntry, 'pack should include GOAL.md');
+  assert(goalEntry.kind === 'goal', 'goal entry kind should be goal');
+  assert(goalEntry.reason, 'goal entry should have a reason');
+  const pkg = pack.entries.find(e => e.path === 'package.json');
+  assert(pkg && pkg.kind === 'package-config', 'pack should include package.json as package-config');
+  const changed = pack.entries.find(e => e.path === 'src/feature.ts');
+  assert(changed && changed.kind === 'git-changed', 'pack should include changed file src/feature.ts');
+  const related = pack.entries.find(e => e.path === 'modules/feature.md');
+  assert(related && related.kind === 'module-doc', 'pack should include related module doc');
+  // Every entry must have a reason
+  for (const e of pack.entries) {
+    assert(typeof e.reason === 'string' && e.reason.length > 0, `entry ${e.path} missing reason`);
+  }
+
+  // Disk artifacts
+  const onDisk = JSON.parse(fs.readFileSync(path.join(DATA_DIR, '_ai', TEMP_SLUG, 'context-packs', 'run-unit-1', 'context-pack.json'), 'utf-8'));
+  assert(onDisk.runId === 'run-unit-1', 'on-disk runId should match');
+
+  // 3. Large / binary file is summarized or skipped
+  const repo2 = makeRepo({ kind: 'binary-commit' });
+  const kbBase2 = path.join(DATA_DIR, 'projects', TEMP_SLUG + '-2');
+  fs.mkdirSync(kbBase2, { recursive: true });
+  fs.writeFileSync(path.join(kbBase2, 'GOAL.md'), '# Goal\n');
+  const commits2 = repo2.commits.slice().reverse();
+  const pack2 = await buildContextPack({
+    project: { slug: TEMP_SLUG + '-2', kbPath: kbBase2, gitPath: repo2.path, localPath: repo2.path },
+    runId: 'run-binary-1',
+    trigger: 'commits',
+    commits: commits2,
+  });
+  const big = pack2.entries.find(e => e.path === 'big.bin');
+  if (big) {
+    assert(big.binary || big.skipped === 'too-large' || big.truncated, 'big file should be marked binary/skipped/truncated');
+  }
+  fs.rmSync(kbBase2, { recursive: true, force: true });
+  repo2.cleanup();
+
+  // 4. Path-traversal attempt is rejected
+  const ok = isSafePath(kbBase, '..\\..\\escape.md');
+  // On Windows, ..\\ becomes normalized. The resolved path should still be inside kbBase.
+  // Test the explicit scenario:
+  assert(!isSafePath(kbBase, '..\\..\\..\\..\\Windows\\evil.txt') || path.resolve(kbBase, '..\\..\\..\\..\\Windows\\evil.txt').startsWith(path.resolve(kbBase)),
+    'path traversal must be rejected');
+
+  repo.cleanup();
+
+  // 5. Server tests
+  const _spawned = spawnServer({ root: ROOT, port: Number(PORT), dataDir: DATA_DIR, tag: 'context-pack', });
+  const child = _spawned.child;
+  let serverOutput = '';
+  child.stdout.on('data', d => { serverOutput += d.toString(); });
+  child.stderr.on('data', d => { serverOutput += d.toString(); });
+
+  try {
+    await cleanup();
+    await waitForServer();
+    let r = await json('PATCH', '/api/settings', { knowledge: { rootPath: path.join(DATA_DIR, 'knowledge') } });
+    assert(r.res.ok, `knowledge root setup should succeed: ${JSON.stringify(r.data)}`);
+
+    // 6. POST /api/projects/:slug/context-pack for an initial pack
+    const initRepo = makeRepo({ kind: 'one-commit' });
+    const slug = TEMP_SLUG;
+    r = await json('POST', '/api/projects/import', {
+      projectId: slug,
+      displayName: 'TASK-006',
+      localPath: initRepo.path,
+    });
+    assert(r.res.ok, `v2 import should succeed: ${JSON.stringify(r.data)}`);
+    const kbPath = r.data.config.knowledgePath;
+    fs.writeFileSync(path.join(kbPath, 'GOAL.md'), '# Goal — server test\n');
+
+    r = await json('POST', `/api/projects/${slug}/context-pack`, { trigger: 'initial' });
+    assert(r.res.ok, 'context-pack initial should succeed');
+    assert(r.data.contextPack.entries.length > 0, 'context pack should have entries');
+    assert(r.data.contextPack.entries.find(e => e.path === 'GOAL.md'), 'goal should be in pack');
+
+    r = await json('POST', `/api/projects/${slug}/context-pack`, { trigger: 'commits' });
+    assert(r.res.ok, 'context-pack commits should succeed');
+    assert(r.data.contextPack.commitCount === 0, 'commits trigger should not treat pre-import history as pending');
+
+    // 7. Bad slug
+    r = await json('POST', '/api/projects/%5Ebad/context-pack', {});
+    assert(!r.res.ok && r.res.status === 400, 'bad project id should 400');
+
+    initRepo.cleanup();
+    console.log('TASK-006 context pack test passed');
+  } catch (e) {
+    console.error('TASK-006 context pack test failed:', e.message);
+    if (serverOutput) console.error(serverOutput);
+    process.exitCode = 1;
+  } finally {
+    await cleanup().catch(() => {});
+    child.kill();
+  }
+})();

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

@@ -0,0 +1,119 @@
+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 { 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 { localDate } = require('../lib/conversation-query-service');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const PORT = 8250 + (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-conversation-api-'));
+  const layout = new StorageLayout({ dataDir });
+  const settings = new SettingsStore({ layout });
+  const registry = new ProjectRegistryStore({ layout });
+  const projects = new ProjectStore({ layout });
+  await settings.initialize({ knowledge: { rootPath: path.join(dataDir, 'knowledge') } });
+  await registry.initialize();
+  const projectId = 'project-conversation-api';
+  const repoPath = path.join(dataDir, 'repo');
+  const knowledgePath = path.join(dataDir, 'knowledge', projectId);
+  fs.mkdirSync(repoPath, { recursive: true });
+  fs.mkdirSync(knowledgePath, { recursive: true });
+  await projects.create(projectId, {
+    displayName: 'Conversation API', storageName: 'conversation-api', repoPath, knowledgePath,
+  }, { conversationBaselineCursor: 0, conversation: { lastConsumedCursor: 0, captureStatus: 'captured' } });
+  await registry.add(projectId, { displayNameSnapshot: 'Conversation API' });
+  const store = new ConversationStore({ layout, projectStore: projects });
+  const repoIdentity = { repoId: 'conversation-api-repo' };
+  const unsafePrompt = '<script>alert("conversation-body")</script> Keep this as plain text.';
+  async function append(eventId, sequence, turnId, role, content, capturedAt) {
+    return (await store.appendEvent(projectId, {
+      eventId, sequence, source: 'codex', eventType: role === 'user' ? 'user_prompt' : 'assistant_response', role, content,
+      sessionId: 'session-api', turnId, repoIdentity, projectPath: repoPath, branch: 'main', headAtCapture: '0'.repeat(40),
+      capturedAt, identityConfidence: 'high', captureStatus: 'captured',
+    })).event;
+  }
+  const r1 = await append('r1', 1, 'turn-1', 'user', unsafePrompt, '2026-08-18T01:00:00.000Z');
+  const a1 = await append('a1', 2, 'turn-1', 'assistant', 'Rendered only as plain assistant text.', '2026-08-18T01:01:00.000Z');
+  const r2 = await append('r2', 3, 'turn-2', 'user', 'Second prompt.', '2026-08-18T02:00:00.000Z');
+  const a2 = await append('a2', 4, 'turn-2', 'assistant', 'Second reply.', '2026-08-18T02:01:00.000Z');
+  await append('r3', 5, 'turn-3', 'user', 'Third prompt.', '2026-08-18T03:00:00.000Z');
+  await append('r4', 6, 'turn-other-date', 'user', 'Other date prompt.', '2026-08-19T03:00:00.000Z');
+  const projectEvent = event => ({ eventId: event.eventId, sequence: event.sequence, content: event.content, contentHash: event.contentHash, capturedAt: event.capturedAt });
+  store.writeSnapshot(projectId, {
+    commitSha: '1'.repeat(40), repoIdentity, parentSha: null, boundaryStartCursor: 0, boundaryEndCursor: 2, status: 'available',
+    turns: [{ turnId: 'turn-1', source: 'codex', sessionId: 'session-api', bindingKind: 'direct', userEvents: [projectEvent(r1)], assistantEvents: [projectEvent(a1)] }],
+  });
+  store.writeSnapshot(projectId, {
+    commitSha: '3'.repeat(40), repoIdentity, parentSha: '2'.repeat(40), boundaryStartCursor: 5, boundaryEndCursor: 5, status: 'available',
+    turns: [{ turnId: 'turn-2', source: 'codex', sessionId: 'session-api', bindingKind: 'shared-spanning', userEvents: [projectEvent(r2)], assistantEvents: [projectEvent(a2)] }],
+  });
+  store.writeSnapshot(projectId, {
+    commitSha: '2'.repeat(40), repoIdentity, parentSha: '1'.repeat(40), boundaryStartCursor: 2, boundaryEndCursor: 4, status: 'available',
+    turns: [{ turnId: 'turn-2', source: 'codex', sessionId: 'session-api', bindingKind: 'shared-spanning', userEvents: [projectEvent(r2)], assistantEvents: [projectEvent(a2)] }],
+  });
+
+  const spawned = spawnServer({ root: ROOT, port: PORT, dataDir, tag: 'conversation-api', extraEnv: { KB_SKIP_MIGRATION: '1' } });
+  try {
+    await waitForServer();
+    let response = await fetch(`${BASE}/api/conversations/projects`);
+    let body = await response.json();
+    assert.strictEqual(response.status, 200);
+    assert.deepStrictEqual(body.projects.map(project => project.projectId), [projectId]);
+    assert.strictEqual(Object.hasOwn(body.projects[0], 'repoPath'), false, 'project picker payload must not expose raw repository paths');
+
+    const date = localDate(r1.capturedAt);
+    response = await fetch(`${BASE}/api/conversations/turns?projectId=${projectId}&date=${date}&limit=2`);
+    body = await response.json();
+    assert.strictEqual(response.status, 200, JSON.stringify(body));
+    assert.strictEqual(body.turns.length, 2);
+    assert(body.nextCursor && body.hasMore);
+    const firstPage = body.turns;
+    response = await fetch(`${BASE}/api/conversations/turns?projectId=${projectId}&date=${date}&limit=2&cursor=${encodeURIComponent(body.nextCursor)}`);
+    const secondPage = await response.json();
+    assert.strictEqual(secondPage.turns.length, 1);
+    const allTurns = [...firstPage, ...secondPage.turns];
+    const turn1 = allTurns.find(turn => turn.turnId === 'turn-1');
+    const turn2 = allTurns.find(turn => turn.turnId === 'turn-2');
+    const turn3 = allTurns.find(turn => turn.turnId === 'turn-3');
+    assert.strictEqual(turn1.userPrompt, unsafePrompt, 'conversation body should remain exact business data');
+    assert.strictEqual(turn1.renderAs, 'plain-text', 'payload must instruct hosts to avoid HTML interpretation');
+    assert.strictEqual(turn1.annotation.status, 'committed');
+    assert.strictEqual(turn1.annotation.commits[0].shortSha, '1111111');
+    assert.strictEqual(turn2.annotation.status, 'associated');
+    assert.deepStrictEqual(turn2.annotation.commits.map(commit => commit.shortSha), ['2222222'], 'stale shared-spanning annotations after the next user turn are hidden');
+    assert.strictEqual(turn3.annotation.status, 'uncommitted');
+    assert(allTurns.every(turn => turn.date === date));
+
+    response = await fetch(`${BASE}/api/conversations/turns?projectId=${projectId}&date=2026-08-19&cursor=${encodeURIComponent(body.nextCursor)}`);
+    assert.strictEqual(response.status, 409, 'cursor must be bound to one project/date query');
+    response = await fetch(`${BASE}/api/conversations/sessions?projectId=${projectId}`);
+    assert.strictEqual(response.status, 404, 'default product API must not expose source/session diagnostic routes');
+
+    response = await fetch(`${BASE}/api/logs/export`);
+    const exportedLogs = await response.text();
+    assert(!exportedLogs.includes('conversation-body'), 'conversation content must never leak into structured logs or export');
+    console.log('conversation-api-test PASS');
+  } finally {
+    await spawned.cleanup();
+  }
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+});

package/_site/_test/conversation-store-test.js

@@ -0,0 +1,136 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { SCHEMAS } = require('../lib/contracts');
+const { StorageLayout } = require('../lib/storage-layout');
+const { ConversationStore, sha256 } = require('../lib/conversation-store');
+
+(async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-conversation-store-'));
+  const dataDir = path.join(root, 'data');
+  const knowledgeRoot = path.join(root, 'knowledge');
+  fs.mkdirSync(knowledgeRoot, { recursive: true });
+  const layout = new StorageLayout({ dataDir });
+  const logRecords = [];
+  const store = new ConversationStore({
+    layout,
+    logger: { async info(event, message, input) { logRecords.push({ event, message, input }); } },
+  });
+  const projectId = 'project-conversation';
+  const eventsPath = layout.getProjectConversationEventsPath(projectId);
+  assert.strictEqual(fs.existsSync(eventsPath), false, 'conversation business data must be lazy-created');
+
+  const privatePrompt = 'Implement secret conversation behavior without logging this body.';
+  const user = {
+    eventId: 'event-user-1',
+    sequence: 10,
+    source: 'codex',
+    eventType: 'user_prompt',
+    role: 'user',
+    content: privatePrompt,
+    sessionId: 'session-1',
+    turnId: 'turn-1',
+    projectPath: path.join(root, 'repo'),
+    repoIdentity: { commonDir: path.join(root, 'repo', '.git') },
+    branch: 'main',
+    headAtCapture: 'a'.repeat(40),
+    capturedAt: '2026-08-18T01:00:00.000Z',
+    rawEventType: 'user-prompt-submit',
+    identityConfidence: 'high',
+    captureStatus: 'captured',
+  };
+  const concurrent = await Promise.all(Array.from({ length: 8 }, () => store.appendEvent(projectId, user)));
+  assert.strictEqual(concurrent.filter(result => result.appended).length, 1, 'eventId dedupe must be atomic under overlap');
+  assert.strictEqual(store.readEvents(projectId).length, 1);
+  assert.strictEqual(store.readEvents(projectId)[0].content, privatePrompt, 'full prompt belongs in the private business store');
+  assert.strictEqual(store.readEvents(projectId)[0].contentHash, sha256(privatePrompt));
+  assert(!JSON.stringify(logRecords).includes(privatePrompt), 'conversation body must never enter structured logs');
+  assert(JSON.stringify(logRecords).includes(sha256(privatePrompt)), 'logs may retain body hash for correlation');
+
+  await assert.rejects(
+    () => store.appendEvent(projectId, { ...user, content: 'different body' }),
+    error => error.code === 'DATA_CORRUPT',
+    'same eventId with different content must never be silently deduplicated',
+  );
+  await store.appendEvent(projectId, {
+    ...user,
+    eventId: 'event-assistant-1',
+    sequence: 11,
+    eventType: 'assistant_response',
+    role: 'assistant',
+    content: 'Implemented and verified.',
+    capturedAt: '2026-08-18T01:01:00.000Z',
+  });
+
+  const legacy = {
+    schema: SCHEMAS.requirement,
+    id: 'req-legacy-1',
+    projectId,
+    ts: '2026-08-18T00:30:00.000Z',
+    client: 'claude',
+    sessionId: 'legacy-session',
+    branch: 'main',
+    headAtRecord: 'b'.repeat(40),
+    requirement: 'Legacy explicit requirement.',
+    requirementHash: sha256('Legacy explicit requirement.'),
+    commitSha: 'c'.repeat(40),
+  };
+  const imported = await store.importLegacyRequirements(projectId, [legacy, legacy]);
+  assert.strictEqual(imported.filter(result => result.appended).length, 1, 'legacy adapter must share eventId dedupe with Bridge events');
+  const legacyEvent = store.readEvents(projectId).find(event => event.legacyRequirementId === legacy.id);
+  assert.strictEqual(legacyEvent.source, 'claude-code');
+  assert.strictEqual(legacyEvent.captureStatus, 'legacy-explicit-adapter');
+  assert.strictEqual(legacyEvent.sequence, null, 'legacy evidence must not invent a Bridge cursor');
+
+  const commitSha = 'd'.repeat(40);
+  const boundary = store.writeBoundary(projectId, {
+    commitSha,
+    repoIdentity: user.repoIdentity,
+    parentShas: ['c'.repeat(40)],
+    branch: 'main',
+    committedAt: '2026-08-18T01:00:30.000Z',
+    bridgeCursorAtCommit: 10,
+    openTurnIdsAtCommit: ['turn-1'],
+    operationId: 'op-boundary-1',
+  });
+  assert.strictEqual(boundary.schema, SCHEMAS.gitCommitBoundary);
+  assert(fs.existsSync(layout.getProjectCommitBoundaryPath(projectId, commitSha)));
+
+  const snapshot = store.writeSnapshot(projectId, {
+    commitSha,
+    repoIdentity: user.repoIdentity,
+    parentSha: 'c'.repeat(40),
+    boundaryStartCursor: 0,
+    boundaryEndCursor: 10,
+    status: 'available',
+    turns: [{
+      turnId: 'turn-1',
+      source: 'codex',
+      sessionId: 'session-1',
+      bindingKind: 'direct',
+      userEvents: [{ eventId: 'event-user-1', sequence: 10, content: privatePrompt, contentHash: sha256(privatePrompt), capturedAt: user.capturedAt }],
+      assistantEvents: [],
+    }],
+    excludedFuturePromptCount: 0,
+    finalizedAt: '2026-08-18T01:02:00.000Z',
+  });
+  assert(snapshot.snapshotHash.startsWith('sha256:'));
+  assert.strictEqual(store.readSnapshot(projectId, commitSha).turns[0].userEvents[0].content, privatePrompt);
+  await assert.rejects(
+    async () => store.writeSnapshot(projectId, { ...snapshot, status: 'ambiguous', finalizedAt: snapshot.finalizedAt }),
+    error => error.code === 'IMMUTABLE_FIELD',
+  );
+  assert(!layout.getProjectCommitConversationPath(projectId, commitSha).startsWith(knowledgeRoot), 'conversation evidence must remain outside the user Markdown root');
+
+  const failingProject = 'project-append-failure';
+  const blocker = layout.getProjectConversationEventsPath(failingProject);
+  fs.mkdirSync(blocker, { recursive: true });
+  await assert.rejects(() => store.appendEvent(failingProject, { ...user, eventId: 'event-fail-1' }));
+  assert.deepStrictEqual(fs.readdirSync(blocker), [], 'failed append must not create partial event data');
+
+  console.log('conversation-store-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+});