@sanqianx/project-knowledge 4.6.1

package/_site/_test/knowledge-promotion-recovery-test.js

@@ -0,0 +1,260 @@
+// Run: node _site/_test/knowledge-promotion-recovery-test.js
+
+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 { ProjectRegistryStore } = require('../lib/project-registry-store');
+const { ProjectStore } = require('../lib/project-store');
+const { claimFingerprint } = require('../lib/commit-reconciler');
+const { KnowledgePromotionService, MANIFEST_SCHEMA, hashBuffer } = require('../lib/knowledge-promotion');
+
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), `kb-promotion-${process.pid}-`));
+const layout = new StorageLayout({ dataDir: path.join(temp, 'data') });
+const registry = new ProjectRegistryStore({ layout });
+const projects = new ProjectStore({ layout });
+let sequence = 0;
+
+async function addProject(projectId) {
+  const repoPath = path.join(temp, 'repos', projectId);
+  const knowledgePath = path.join(temp, 'knowledge', projectId);
+  fs.mkdirSync(repoPath, { recursive: true });
+  fs.mkdirSync(knowledgePath, { recursive: true });
+  await projects.create(projectId, {
+    displayName: projectId,
+    storageName: projectId,
+    repoPath,
+    knowledgePath,
+    aiProfileId: 'test-profile',
+  }, { trackingStartCommit: '1'.repeat(40), trackingMode: 'normal' });
+  await registry.add(projectId, { displayName: projectId });
+  return projects.readConfig(projectId);
+}
+
+async function activate(projectId, requirementIds = []) {
+  sequence += 1;
+  const commitSha = sequence.toString(16).padStart(40, '0');
+  const claim = {
+    schema: SCHEMAS.commitClaim,
+    projectId,
+    commitSha,
+    parents: ['1'.repeat(40)],
+    triggerFirstSeen: 'git-hook',
+    requirementIds,
+    requirementBinding: requirementIds.length ? 'explicit' : 'unavailable',
+    promptTemplateVersion: 2,
+    promptHash: `sha256:prompt-${sequence}`,
+    patchHash: `sha256:patch-${sequence}`,
+    evidenceHash: `sha256:evidence-${sequence}`,
+    knowledgePath: projects.readConfig(projectId).knowledgePath,
+    runId: `run-${sequence}`,
+    operationId: `op-${sequence}`,
+    phase: 'evidence.prepared',
+    attempt: 1,
+  };
+  claim.fingerprint = claimFingerprint(claim);
+  await projects.updateState(projectId, state => {
+    state.analysis.activeClaim = claim;
+    state.analysis.status = 'evidence.prepared';
+    state.analysis.lastError = null;
+  });
+  return claim;
+}
+
+function analyzerFor(operations) {
+  return {
+    calls: 0,
+    async runClaim(input) {
+      this.calls += 1;
+      const manifestOperations = [];
+      for (const operation of operations) {
+        let digest = null;
+        if (operation.operation !== 'delete') {
+          const target = path.join(input.stagingPath, 'files', ...operation.path.split('/'));
+          fs.mkdirSync(path.dirname(target), { recursive: true });
+          fs.writeFileSync(target, operation.content, 'utf8');
+          digest = hashBuffer(Buffer.from(operation.content));
+        }
+        manifestOperations.push({
+          path: operation.path,
+          operation: operation.operation,
+          sha256: digest,
+          reason: operation.reason || 'Verified by the active commit patch.',
+          evidenceReferences: operation.evidenceReferences || [`commit:${input.claim.commitSha}`, `patch:${input.claim.patchHash}`],
+        });
+      }
+      fs.writeFileSync(input.manifestPath, JSON.stringify({
+        schema: MANIFEST_SCHEMA,
+        projectId: input.projectId,
+        runId: input.claim.runId,
+        commitSha: input.claim.commitSha,
+        operations: manifestOperations,
+      }, null, 2), 'utf8');
+      return { ok: true };
+    },
+  };
+}
+
+(async () => {
+  await registry.initialize();
+
+  const validConfig = await addProject('project-valid');
+  fs.writeFileSync(path.join(validConfig.knowledgePath, 'README.md'), '# Old README\n\nOld fact.\n', 'utf8');
+  fs.mkdirSync(path.join(validConfig.knowledgePath, 'changes'), { recursive: true });
+  fs.writeFileSync(path.join(validConfig.knowledgePath, 'changes', 'old.md'), '# Old Change\n\nRemove me.\n', 'utf8');
+  const validClaim = await activate('project-valid', ['req-valid']);
+  const validAnalyzer = analyzerFor([
+    { path: 'README.md', operation: 'replace', content: '# Project Valid\n\nVerified current fact.\n' },
+    { path: 'modules/core.md', operation: 'create', content: '# Core Module\n\nThe active commit adds the core module.\n' },
+    { path: 'changes/old.md', operation: 'delete' },
+  ]);
+  let enqueued = 0;
+  const validService = new KnowledgePromotionService({
+    layout,
+    projectStore: projects,
+    analyzer: validAnalyzer,
+    indexService: { enqueue: async () => { enqueued += 1; return { ok: true }; } },
+  });
+  const promoted = await validService.processClaim({ projectId: 'project-valid', config: validConfig, claim: validClaim, prompt: 'frozen prompt' });
+  assert.strictEqual(promoted.stateAdvanced, true);
+  assert.strictEqual(fs.readFileSync(path.join(validConfig.knowledgePath, 'README.md'), 'utf8'), '# Project Valid\n\nVerified current fact.\n');
+  assert(fs.existsSync(path.join(validConfig.knowledgePath, 'modules', 'core.md')));
+  assert.strictEqual(fs.existsSync(path.join(validConfig.knowledgePath, 'changes', 'old.md')), false);
+  const validState = projects.readState('project-valid');
+  assert.strictEqual(validState.lastAnalyzedCommit, validClaim.commitSha);
+  assert.strictEqual(validState.analysis.activeClaim, null);
+  assert.deepStrictEqual(validState.analysis.consumedRequirementIds, ['req-valid']);
+  assert.strictEqual(validState.index.dirty, true);
+  assert.strictEqual(enqueued, 1);
+
+  const noOutputConfig = await addProject('project-no-output');
+  const noOutputClaim = await activate('project-no-output');
+  const noOutputService = new KnowledgePromotionService({
+    layout,
+    projectStore: projects,
+    analyzer: { runClaim: async () => ({ ok: true }) },
+  });
+  await assert.rejects(
+    noOutputService.processClaim({ projectId: 'project-no-output', config: noOutputConfig, claim: noOutputClaim, prompt: 'frozen' }),
+    error => error.code === 'DATA_CORRUPT' || error.code === 'ENOENT',
+  );
+  assert.strictEqual(projects.readState('project-no-output').lastAnalyzedCommit, null, 'AI exit 0 without output must not advance');
+
+  const outsideConfig = await addProject('project-outside');
+  const outsideClaim = await activate('project-outside');
+  const outsideService = new KnowledgePromotionService({
+    layout,
+    projectStore: projects,
+    analyzer: analyzerFor([{ path: '../outside.md', operation: 'create', content: '# Outside\n\nUnsafe.\n' }]),
+  });
+  await assert.rejects(
+    outsideService.processClaim({ projectId: 'project-outside', config: outsideConfig, claim: outsideClaim, prompt: 'frozen' }),
+    error => error.code === 'PATH_OUTSIDE_ROOT',
+  );
+  assert.strictEqual(fs.existsSync(path.join(temp, 'knowledge', 'outside.md')), false);
+
+  const placeholderConfig = await addProject('project-placeholder');
+  const placeholderClaim = await activate('project-placeholder');
+  const placeholderService = new KnowledgePromotionService({
+    layout,
+    projectStore: projects,
+    analyzer: analyzerFor([{ path: 'README.md', operation: 'create', content: '# Placeholder\n\nTODO: invent this later.\n' }]),
+  });
+  await assert.rejects(
+    placeholderService.processClaim({ projectId: 'project-placeholder', config: placeholderConfig, claim: placeholderClaim, prompt: 'frozen' }),
+    error => error.code === 'INVALID_ARGUMENT' && /Placeholder/.test(error.message),
+  );
+
+  const rollbackConfig = await addProject('project-rollback');
+  fs.writeFileSync(path.join(rollbackConfig.knowledgePath, 'README.md'), '# Original\n\nKeep this.\n', 'utf8');
+  const rollbackClaim = await activate('project-rollback');
+  const rollbackService = new KnowledgePromotionService({
+    layout,
+    projectStore: projects,
+    analyzer: analyzerFor([
+      { path: 'README.md', operation: 'replace', content: '# Replaced\n\nNew verified fact.\n' },
+      { path: 'modules/new.md', operation: 'create', content: '# New Module\n\nNew verified module.\n' },
+    ]),
+    fault: stage => { if (stage === 'operation-applied:0') throw new Error('injected crash after first apply'); },
+  });
+  await assert.rejects(
+    rollbackService.processClaim({ projectId: 'project-rollback', config: rollbackConfig, claim: rollbackClaim, prompt: 'frozen' }),
+    /injected crash/,
+  );
+  assert.strictEqual(projects.readState('project-rollback').lastAnalyzedCommit, null);
+  const rollbackRecovery = new KnowledgePromotionService({ layout, projectStore: projects });
+  const rolledBack = await rollbackRecovery.recoverAll();
+  assert(rolledBack.some(item => item.phase === 'rolled-back'));
+  assert.strictEqual(fs.readFileSync(path.join(rollbackConfig.knowledgePath, 'README.md'), 'utf8'), '# Original\n\nKeep this.\n');
+  assert.strictEqual(fs.existsSync(path.join(rollbackConfig.knowledgePath, 'modules', 'new.md')), false);
+
+  const recoverConfig = await addProject('project-recover-state');
+  const recoverClaim = await activate('project-recover-state');
+  const recoverAnalyzer = analyzerFor([{ path: 'README.md', operation: 'create', content: '# Recovered\n\nVerified before the crash.\n' }]);
+  const crashBeforeState = new KnowledgePromotionService({
+    layout,
+    projectStore: projects,
+    analyzer: recoverAnalyzer,
+    fault: stage => { if (stage === 'promotion-verified') throw new Error('crash before state advance'); },
+  });
+  await assert.rejects(
+    crashBeforeState.processClaim({ projectId: 'project-recover-state', config: recoverConfig, claim: recoverClaim, prompt: 'frozen' }),
+    /crash before state advance/,
+  );
+  assert.strictEqual(projects.readState('project-recover-state').lastAnalyzedCommit, null);
+  const recovery = new KnowledgePromotionService({ layout, projectStore: projects });
+  const recovered = await recovery.recoverAll();
+  assert(recovered.some(item => item.stateAdvanced === true));
+  assert.strictEqual(projects.readState('project-recover-state').lastAnalyzedCommit, recoverClaim.commitSha);
+  assert.strictEqual(recoverAnalyzer.calls, 1, 'journal recovery must not call AI again');
+
+  const stateFailureConfig = await addProject('project-state-failure');
+  const stateFailureClaim = await activate('project-state-failure');
+  const stateFailureAnalyzer = analyzerFor([{ path: 'README.md', operation: 'create', content: '# State Repair\n\nVerified before persistence failed.\n' }]);
+  const failingStore = {
+    readState: projectId => projects.readState(projectId),
+    updateState: async () => { throw new Error('injected state persistence failure'); },
+  };
+  const stateFailureService = new KnowledgePromotionService({
+    layout,
+    projectStore: failingStore,
+    analyzer: stateFailureAnalyzer,
+  });
+  await assert.rejects(
+    stateFailureService.processClaim({ projectId: 'project-state-failure', config: stateFailureConfig, claim: stateFailureClaim, prompt: 'frozen' }),
+    /state persistence failure/,
+  );
+  assert(fs.existsSync(path.join(stateFailureConfig.knowledgePath, 'README.md')), 'verified Markdown should remain promoted while journal awaits state repair');
+  assert.strictEqual(projects.readState('project-state-failure').lastAnalyzedCommit, null);
+  const stateRepair = new KnowledgePromotionService({ layout, projectStore: projects });
+  await stateRepair.recoverAll();
+  assert.strictEqual(projects.readState('project-state-failure').lastAnalyzedCommit, stateFailureClaim.commitSha, 'startup recovery should repair state without another AI run');
+  assert.strictEqual(stateFailureAnalyzer.calls, 1);
+
+  const conflictConfig = await addProject('project-conflict');
+  fs.writeFileSync(path.join(conflictConfig.knowledgePath, 'README.md'), '# Before\n\nOriginal.\n', 'utf8');
+  const conflictClaim = await activate('project-conflict');
+  const conflictService = new KnowledgePromotionService({
+    layout,
+    projectStore: projects,
+    analyzer: analyzerFor([{ path: 'README.md', operation: 'replace', content: '# After\n\nPromoted.\n' }]),
+    fault: stage => {
+      if (stage === 'manifest-validated') fs.writeFileSync(path.join(conflictConfig.knowledgePath, 'README.md'), '# User Edit\n\nDo not overwrite.\n', 'utf8');
+    },
+  });
+  await assert.rejects(
+    conflictService.processClaim({ projectId: 'project-conflict', config: conflictConfig, claim: conflictClaim, prompt: 'frozen' }),
+    error => error.code === 'PROJECT_BUSY',
+  );
+  assert.strictEqual(fs.readFileSync(path.join(conflictConfig.knowledgePath, 'README.md'), 'utf8'), '# User Edit\n\nDo not overwrite.\n');
+  assert.strictEqual(projects.readState('project-conflict').lastAnalyzedCommit, null);
+
+  console.log('knowledge-promotion-recovery-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+}).finally(() => {
+  fs.rmSync(temp, { recursive: true, force: true });
+});

package/_site/_test/knowledge-query-test.js

@@ -0,0 +1,54 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+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 { KnowledgeToolRuntime } = require('../lib/knowledge-tool-runtime');
+
+(async () => {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-query-v2-'));
+  const layout = new StorageLayout({ dataDir: path.join(temp, 'data') });
+  const settings = new SettingsStore({ layout });
+  const registry = new ProjectRegistryStore({ layout });
+  const projects = new ProjectStore({ layout });
+  await settings.initialize({ knowledge: { rootPath: path.join(temp, 'knowledge') } });
+  await registry.initialize();
+  const fixtures = [
+    ['project-api', 'API', 'API refresh tokens rotate after authentication.'],
+    ['project-web', 'Web', 'Web login keeps a short-lived browser session.'],
+    ['project-secret', 'Secret', 'This unrelated project must stay out of scope.'],
+  ];
+  for (const [projectId, title, content] of fixtures) {
+    const knowledgePath = path.join(temp, 'knowledge', projectId);
+    fs.mkdirSync(path.join(knowledgePath, 'changes'), { recursive: true });
+    fs.writeFileSync(path.join(knowledgePath, 'changes', 'decision.md'), `# ${title}\n\n${content}\n`, 'utf8');
+    await projects.create(projectId, {
+      displayName: title, storageName: projectId, repoPath: temp, knowledgePath,
+      relatedProjectIds: projectId === 'project-api' ? ['project-web'] : [],
+    }, { index: { dirty: true, generation: 1 } });
+    await registry.add(projectId, { displayNameSnapshot: title });
+  }
+  const runtime = new KnowledgeToolRuntime({ layout, settingsStore: settings, registryStore: registry, projectStore: projects });
+  try {
+    const search = await runtime.search({ projectId: 'project-api', query: 'login session tokens', limit: 10 });
+    assert.strictEqual(search.source, 'knowledge-retrieval-service');
+    assert.strictEqual(search.backend, 'markdown-hybrid-fallback');
+    assert(search.results.some(row => row.scope_project_id === 'project-api'));
+    assert(search.results.some(row => row.scope_project_id === 'project-web'));
+    assert(search.results.every(row => row.scope_project_id !== 'project-secret'));
+    const asked = await runtime.ask({ projectId: 'project-api', query: 'refresh tokens', limit: 5 });
+    assert(asked.citations.length > 0 && /refresh tokens/i.test(asked.answer));
+    const entry = await runtime.get({ projectId: 'project-api', entryId: 'changes/decision.md' });
+    assert.match(entry.chunks[0].chunk_text, /rotate after authentication/);
+    await assert.rejects(runtime.get({ projectId: 'project-api', entryId: '../project-secret/changes/decision.md' }), error => error.code === 'PATH_OUTSIDE_ROOT');
+    const history = await runtime.history({ projectId: 'project-api' });
+    assert.strictEqual(history.results[0].entry_id, 'changes/decision.md');
+    assert.strictEqual(fs.existsSync(path.join(layout.getDataDir(), 'knowledge-scopes.json')), false, 'read queries must not create a second scope registry');
+    console.log('knowledge-query-test: PASS');
+  } finally {
+    await runtime.close();
+  }
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/knowledge-retrieval-service-test.js

@@ -0,0 +1,77 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+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');
+
+(async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-retrieval-'));
+  const layout = new StorageLayout({ dataDir: path.join(root, 'data') });
+  const registry = new ProjectRegistryStore({ layout });
+  const projects = new ProjectStore({ layout });
+  await registry.initialize();
+
+  async function addProject(projectId, relatedProjectIds = []) {
+    const knowledgePath = path.join(root, 'knowledge', projectId);
+    fs.mkdirSync(path.join(knowledgePath, 'modules'), { recursive: true });
+    await projects.create(projectId, {
+      displayName: projectId,
+      storageName: projectId,
+      repoPath: path.join(root, 'repos', projectId),
+      knowledgePath,
+      relatedProjectIds,
+    }, { index: { dirty: true, generation: 9 } });
+    await registry.add(projectId, { displayNameSnapshot: projectId });
+    return knowledgePath;
+  }
+
+  const primary = await addProject('project-primary', ['project-related']);
+  const related = await addProject('project-related');
+  const secret = await addProject('project-secret');
+  for (let index = 0; index < 146; index += 1) {
+    fs.writeFileSync(path.join(primary, 'modules', `distractor-${String(index).padStart(3, '0')}.md`), `# Distractor ${index}\n\nRefresh credential lifecycle notes repeated for semantic distraction.\n`, 'utf8');
+  }
+  fs.writeFileSync(path.join(primary, 'modules', 'zzzz-token-rotation.md'), `---\ntags: [auth]\nsourcePaths: [src/security/token-rotation.js]\nroutes: [/api/tokens]\nsymbols: [TokenRotator]\n---\n# Rotation invariants\n\nThe rotation invariant is authoritative.\n`, 'utf8');
+  fs.writeFileSync(path.join(primary, 'modules', 'symbol-only.md'), `---\nsymbols: [SessionEpoch]\n---\n# Epoch contract\n\nEpoch invalidation behavior.\n`, 'utf8');
+  fs.writeFileSync(path.join(primary, 'modules', 'route-only.md'), `---\nroutes: [/v2/device-sessions]\n---\n# Device route\n\nDevice session route behavior.\n`, 'utf8');
+  fs.writeFileSync(path.join(primary, 'modules', 'tag-only.md'), `---\ntags: [credential-audit]\n---\n# Audit tag\n\nAudit behavior.\n`, 'utf8');
+  fs.writeFileSync(path.join(related, 'modules', 'related-rotation.md'), `---\nsourcePaths: [src/security/token-rotation.js]\n---\n# Related rotation\n\nRelated project evidence.\n`, 'utf8');
+  fs.writeFileSync(path.join(secret, 'modules', 'secret-rotation.md'), `---\nsourcePaths: [src/security/token-rotation.js]\n---\n# Secret rotation\n\nThis project is outside the explicit scope.\n`, 'utf8');
+
+  const service = new KnowledgeRetrievalService({ layout, registryStore: registry, projectStore: projects });
+  const snapshot = {
+    turns: [{
+      userEvents: [{ content: 'Implement the refresh credential lifecycle and preserve credential-audit behavior.' }],
+      assistantEvents: [{ content: 'A secondary hint mentions device sessions.' }],
+    }],
+  };
+  const evidence = {
+    commitSha: 'a'.repeat(40),
+    subject: 'update TokenRotator SessionEpoch /v2/device-sessions',
+    files: [{ status: 'M', path: 'src/security/token-rotation.js' }],
+  };
+  const first = await service.retrieveForCommit({ projectId: 'project-primary', conversationSnapshot: snapshot, commitEvidence: evidence, contextBudget: 64 * 1024 });
+  const second = await service.retrieveForCommit({ projectId: 'project-primary', conversationSnapshot: snapshot, commitEvidence: evidence, contextBudget: 64 * 1024 });
+  assert.strictEqual(first.manifestHash, second.manifestHash, 'deterministic inputs must produce a stable retrieval manifest hash');
+  assert.strictEqual(first.manifest.backend, 'missing', 'missing index must use the safe current-Markdown fallback');
+  assert(first.manifest.currentChunkCount >= 150, 'fixture must exercise a 100-200 document knowledge base');
+  assert.strictEqual(first.entries[0].path, 'modules/zzzz-token-rotation.md', 'exact changed-path metadata must outrank high-semantic distractors and filename order');
+  assert(first.entries[0].selectionSignals.some(signal => signal.startsWith('exact-source-path:')));
+  assert(first.entries.some(entry => entry.path === 'modules/symbol-only.md' && entry.selectionSignals.some(signal => signal.startsWith('structured:'))), 'symbol metadata must participate in recall/rerank');
+  assert(first.entries.some(entry => entry.path === 'modules/route-only.md' && entry.selectionSignals.some(signal => signal.startsWith('structured:'))), 'route metadata must participate in recall/rerank');
+  assert(first.entries.some(entry => entry.path === 'modules/tag-only.md' && entry.selectionSignals.some(signal => signal.startsWith('structured:'))), 'tag metadata must participate in recall/rerank');
+  assert(first.entries.some(entry => entry.projectId === 'project-related'), 'explicit related project scope should be eligible at lower weight');
+  assert(first.entries.every(entry => entry.projectId !== 'project-secret'), 'unrelated projects must never enter the candidate set');
+  assert(first.manifest.selected.every(item => item.documentHash && item.contentHash && item.selectionSignals.length));
+
+  const searched = await service.search({ projectId: 'project-primary', query: 'TokenRotator', limit: 5 });
+  assert.strictEqual(searched.results[0].entry_id, 'modules/zzzz-token-rotation.md');
+  assert(searched.results.every(result => result.scope_project_id !== 'project-secret'));
+  console.log('knowledge-retrieval-service-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+});

package/_site/_test/knowledge-scopes-test.js

@@ -0,0 +1,37 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+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 { KnowledgeToolRuntime } = require('../lib/knowledge-tool-runtime');
+
+(async () => {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-scopes-v2-'));
+  const layout = new StorageLayout({ dataDir: path.join(temp, 'data') });
+  const settings = new SettingsStore({ layout });
+  const registry = new ProjectRegistryStore({ layout });
+  const projects = new ProjectStore({ layout });
+  await settings.initialize({ knowledge: { rootPath: path.join(temp, 'knowledge') } });
+  await registry.initialize();
+  for (const projectId of ['project-api', 'project-web', 'project-transitive']) {
+    const knowledgePath = path.join(temp, 'knowledge', projectId);
+    fs.mkdirSync(knowledgePath, { recursive: true });
+    await projects.create(projectId, {
+      displayName: projectId, storageName: projectId, repoPath: path.join(temp, projectId), knowledgePath,
+      relatedProjectIds: projectId === 'project-api' ? ['project-web'] : projectId === 'project-web' ? ['project-transitive'] : [],
+    });
+    await registry.add(projectId, { displayNameSnapshot: projectId });
+  }
+  const runtime = new KnowledgeToolRuntime({ layout, settingsStore: settings, registryStore: registry, projectStore: projects });
+  const project = runtime.resolveProject({ projectId: 'project-api' });
+  const scopes = runtime.scopes(project);
+  assert.deepStrictEqual(scopes.map(scope => scope.spaceId), ['project:project-api', 'project:project-web']);
+  assert(!scopes.some(scope => scope.projectId === 'project-transitive'), 'related scopes must remain non-transitive');
+  assert.strictEqual(scopes[0].weight, 1);
+  assert.strictEqual(scopes[1].weight, 0.88);
+  assert(!fs.existsSync(path.join(layout.getDataDir(), 'knowledge-scopes.json')), 'scope resolution must derive from immutable project config without side effects');
+  console.log('knowledge-scopes-test PASS');
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/knowledge-storage-location-test.js

@@ -0,0 +1,28 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { StorageLayout } = require('../lib/storage-layout');
+const { SettingsStore } = require('../lib/settings-store');
+
+(async () => {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-storage-location-v2-'));
+  const dataDir = path.join(temp, 'data');
+  const rootA = path.join(temp, 'knowledge-a');
+  const rootB = path.join(temp, 'knowledge-b');
+  const layout = new StorageLayout({ dataDir });
+  const settings = new SettingsStore({ layout });
+  await settings.initialize({ knowledge: { rootPath: rootA } });
+  const indexPath = layout.getIndexPath();
+  fs.mkdirSync(indexPath, { recursive: true });
+  fs.writeFileSync(path.join(indexPath, 'sentinel'), 'derived-index', 'utf8');
+  await settings.updatePatch({ knowledge: { rootPath: rootB } });
+  assert.strictEqual(layout.getIndexPath(), indexPath, 'the internal index path must not follow the user knowledge root');
+  assert.strictEqual(fs.readFileSync(path.join(indexPath, 'sentinel'), 'utf8'), 'derived-index');
+  assert.strictEqual(layout.isPathInside(rootA, indexPath), false);
+  assert.strictEqual(layout.isPathInside(rootB, indexPath), false);
+  assert.strictEqual(layout.getKnowledgeRootPath(settings.read()), path.resolve(rootB));
+  assert(!fs.existsSync(path.join(rootA, '.project-knowledge')));
+  assert(!fs.existsSync(path.join(rootB, '.project-knowledge')));
+  console.log('knowledge-storage-location-test: PASS');
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/knowledge-storage-startup-test.js

@@ -0,0 +1,52 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { StorageLayout } = require('../lib/storage-layout');
+const { SettingsStore } = require('../lib/settings-store');
+const { ProjectRegistryStore } = require('../lib/project-registry-store');
+const { KnowledgeDatabase } = require('../lib/knowledge-db');
+const { EMBEDDING_DIMENSIONS } = require('../lib/knowledge-schema');
+const { spawnServer } = require('./helpers/spawn-server');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const PORT = 7931;
+const BASE_URL = `http://127.0.0.1:${PORT}`;
+
+async function get(route) {
+  const response = await fetch(`${BASE_URL}${route}`);
+  return { response, body: await response.json() };
+}
+
+(async () => {
+  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'knowledge-storage-startup-v2-'));
+  const layout = new StorageLayout({ dataDir });
+  const configuredRoot = path.join(dataDir, 'selected-knowledge-root');
+  const settings = new SettingsStore({ layout });
+  await settings.initialize({ knowledge: { rootPath: configuredRoot } });
+  await new ProjectRegistryStore({ layout }).initialize();
+  const internalIndex = layout.getIndexPath();
+  const database = new KnowledgeDatabase({ dbPath: internalIndex });
+  const vector = new Array(EMBEDDING_DIMENSIONS).fill(0);
+  vector[4] = 1;
+  await database.replaceEntry('project:legacy', 'GOAL.md', [{ chunkOrder: 0, title: 'Legacy', chunkText: 'Fixed internal derived row.', vector }]);
+  await database.close();
+  const spawned = spawnServer({ root: ROOT, port: PORT, dataDir, tag: 'knowledge-storage-startup', extraEnv: { KB_EMBEDDING_FAKE: '1' } });
+  try {
+    let health;
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+      try { health = await get('/api/health'); if (health.response.ok) break; } catch {}
+      await new Promise(resolve => setTimeout(resolve, 100));
+    }
+    assert(health && health.response.ok, 'server did not start');
+    const publicSettings = await get('/api/settings');
+    assert.strictEqual(publicSettings.body.settings.knowledge.rootPath, path.resolve(configuredRoot));
+    const maintenance = await get('/api/knowledge/maintenance');
+    assert.strictEqual(maintenance.body.indexPath, internalIndex);
+    assert(fs.existsSync(internalIndex), 'the derived index must remain under the internal data directory');
+    assert(!fs.existsSync(path.join(configuredRoot, '.project-knowledge')), 'the user knowledge root must not receive internal runtime data');
+    console.log('knowledge-storage-startup-test: PASS');
+  } finally {
+    spawned.child.kill();
+  }
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/knowledge-store-logs-supervision-test.js

@@ -0,0 +1,89 @@
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnServer } = require('./helpers/spawn-server');
+const { makeRepo } = require('./fixtures/make-git-repos');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const PORT = Number(process.env.KB_TASK_012_013_TEST_PORT || 7814);
+const BASE_URL = `http://127.0.0.1:${PORT}`;
+const DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), `kb-store-logs-v2-${process.pid}-`));
+
+async function waitForServer() {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    try { if ((await fetch(`${BASE_URL}/api/health`)).ok) return; } catch {}
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  throw new Error('server did not start');
+}
+
+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();
+  return { response, body: text ? JSON.parse(text) : {} };
+}
+
+(async () => {
+  const repoOne = makeRepo({ kind: 'multi-commit' });
+  const repoTwo = makeRepo({ kind: 'one-commit' });
+  const spawned = spawnServer({ root: ROOT, port: PORT, dataDir: DATA_DIR, tag: 'knowledge-store-logs-v2', extraEnv: { KB_EMBEDDING_FAKE: '1' } });
+  let output = '';
+  spawned.child.stdout.on('data', chunk => { output += chunk; });
+  spawned.child.stderr.on('data', chunk => { output += chunk; });
+  try {
+    await waitForServer();
+    const rootOne = path.join(DATA_DIR, 'knowledge-one');
+    let result = await json('PATCH', '/api/settings', { knowledge: { rootPath: rootOne } });
+    assert(result.response.ok, JSON.stringify(result.body));
+    result = await json('POST', '/api/projects/import', { projectId: 'store-project-one', localPath: repoOne.path, displayName: 'Store one' });
+    assert.strictEqual(result.response.status, 201, JSON.stringify(result.body));
+    const fixedPath = result.body.config.knowledgePath;
+    assert(path.resolve(fixedPath).startsWith(`${path.resolve(rootOne)}${path.sep}`));
+    assert.deepStrictEqual(fs.readdirSync(fixedPath), [], 'import must not generate TODO or initialization knowledge');
+
+    const rootTwo = path.join(DATA_DIR, 'knowledge-two');
+    result = await json('PATCH', '/api/settings', { knowledge: { rootPath: rootTwo } });
+    assert(result.response.ok);
+    result = await json('POST', '/api/projects/import', { projectId: 'store-project-two', localPath: repoTwo.path, displayName: 'Store two' });
+    assert.strictEqual(result.response.status, 201, JSON.stringify(result.body));
+    assert(path.resolve(result.body.config.knowledgePath).startsWith(`${path.resolve(rootTwo)}${path.sep}`));
+    result = await json('GET', '/api/projects/store-project-one');
+    assert.strictEqual(result.body.project.config.knowledgePath, fixedPath, 'global root changes affect only future imports');
+
+    result = await json('PATCH', '/api/settings', { logging: { levels: ['trace', 'debug', 'info', 'warn', 'error', 'fatal'] } });
+    assert.strictEqual(result.response.status, 409, 'logging capture policy must not be a mutable product setting');
+    const publicSettings = await json('GET', '/api/settings');
+    assert.strictEqual(Object.prototype.hasOwnProperty.call(publicSettings.body.settings.logging, 'retentionDays'), false);
+    result = await json('PATCH', '/api/settings', { logging: { retentionDays: 0 } });
+    assert.strictEqual(result.response.status, 409, 'automatic retention settings must be removed');
+    result = await json('PATCH', '/api/settings', { logging: { rootPath: path.join(DATA_DIR, 'external-logs') } });
+    assert.strictEqual(result.response.status, 409, 'logging root must not be configurable');
+    assert(!fs.existsSync(path.join(DATA_DIR, 'external-logs')));
+
+    result = await json('GET', '/api/logs?levels=info,error&pageSize=100');
+    assert(result.response.ok, JSON.stringify(result.body));
+    assert(result.body.entries.some(log => log.event === 'project.import.completed' && log.projectId === 'store-project-one'));
+    assert(result.body.health && ['ok', 'degraded'].includes(result.body.health.status));
+    const state = await json('GET', '/api/state');
+    const one = state.body.projects.find(project => project.projectId === 'store-project-one');
+    assert(one && one.state.trackingStartCommit, 'v2 state should expose the import tracking baseline');
+    assert.strictEqual(one.state.analysis.status, 'idle');
+    assert.strictEqual(one.state.hook.managedVersion, 2);
+
+    result = await json('POST', '/api/knowledge-store/migrate', { execute: false });
+    assert.strictEqual(result.response.status, 404, 'the old storage relocation API must remain removed');
+    console.log('TASK-012/TASK-013 knowledge store, logs, supervision test passed');
+  } catch (error) {
+    if (output) process.stderr.write(output);
+    throw error;
+  } finally {
+    spawned.child.kill();
+    repoOne.cleanup();
+    repoTwo.cleanup();
+  }
+})().catch(error => { console.error(error); process.exitCode = 1; });