@sanqianx/project-knowledge 5.0.24 → 5.0.26

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

@@ -0,0 +1,292 @@
+'use strict';
+// Parallel knowledge lane — retrieval cases RET-001, RET-003, RET-004, RET-005.
+// Every assertion runs against real Markdown on disk and the real vendored
+// knowledge-engine over real loopback HTTP. The vector endpoint is an
+// explicitly declared stub that returns no results, so nothing in this file
+// may be counted as vector-channel evidence.
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const http = require('node:http');
+const crypto = require('node:crypto');
+const fixture = require('./helpers/parallel-knowledge-fixture');
+// The entry point isolates itself: ambient module addresses, live data
+// directories and the real HOME are cleared here, before any product module
+// is loaded, so the test never depends on the caller running `env -u`.
+fixture.isolateProcess();
+const { StorageLayout } = require('../lib/storage-layout');
+const { ProjectStore } = require('../lib/project-store');
+const { ProjectRegistryStore } = require('../lib/project-registry-store');
+const { KnowledgeRetrievalService } = require('../lib/knowledge-retrieval-service');
+const { EngineKnowledgeClient } = require('../lib/engine-knowledge-client');
+const { CHUNKER_VERSION } = require('../lib/markdown-knowledge-indexer');
+const { sha256 } = require('../lib/knowledge-schema');
+const { createEngineServer } = require('../../_modules/knowledge-engine/src/server');
+const AtomicFile = require('../../_modules/knowledge-engine/src/runtime/atomic-file');
+
+const results = [];
+function record(caseId, status, detail) {
+  results.push({ caseId, status, detail });
+  console.log(`CASE ${caseId} ${status} ${JSON.stringify(detail)}`);
+}
+
+async function stubVectorServer() {
+  const requests = [];
+  const server = http.createServer((req, res) => {
+    let body = '';
+    req.on('data', chunk => { body += chunk; });
+    req.on('end', () => {
+      requests.push({ url: req.url, method: req.method, body: body || null });
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: true, results: [], errors: [], projects: [] }));
+    });
+  });
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+  return { requests, url: `http://127.0.0.1:${server.address().port}`, close: () => { server.closeAllConnections(); return new Promise(resolve => server.close(resolve)); } };
+}
+
+// The engine must never reach the user's event bridge (8790) from this lane.
+function forbiddenBridge() {
+  const guard = name => async () => { throw new Error(`event bridge must not be contacted from the test lane (${name})`); };
+  return { registerConsumer: guard('registerConsumer'), listJournals: guard('listJournals'), readEvents: guard('readEvents'), ackConsumerCursor: guard('ackConsumerCursor'), close() {} };
+}
+
+// A declared stub analyzer: it never calls a model, it only stages Markdown
+// so the promotion path can be exercised end to end.
+function stubAnalyzer(events = []) {
+  return {
+    sourceReadMode: 'isolated-frozen-evidence',
+    async runClaim(input) {
+      events.push({ kind: 'start', projectId: input.projectId, sha: input.claim.commitSha });
+      const relative = `changes/${input.claim.commitSha.slice(0, 12)}.md`;
+      const content = `# 真实晋升条目 ${input.claim.commitSha.slice(0, 12)}\n\nRET001TOKEN 事实：本次提交把配额采样改为串行执行。\n\ncommit: ${input.claim.commitSha}\n`;
+      AtomicFile.writeFileAtomic(path.join(input.stagingPath, 'files', relative), content);
+      AtomicFile.writeJsonAtomic(input.manifestPath, {
+        schema: 'knowledge-staging-manifest/v1',
+        projectId: input.projectId,
+        runId: input.claim.runId,
+        commitSha: input.claim.commitSha,
+        operations: [{
+          path: relative,
+          operation: 'create',
+          sha256: `sha256:${crypto.createHash('sha256').update(content).digest('hex')}`,
+          reason: 'Frozen Git evidence',
+          evidenceReferences: [`commit:${input.claim.commitSha}`, `patch:${input.claim.patchHash}`, `conversation:${input.claim.conversationSnapshotHash}`, `retrieval:${input.claim.retrievalManifestHash}`],
+        }],
+      });
+      events.push({ kind: 'finish', projectId: input.projectId, sha: input.claim.commitSha });
+      return { ok: true };
+    },
+  };
+}
+
+(async () => {
+  const root = fixture.makeTempDir('parallel-knowledge-retrieval');
+  const dataDir = path.join(root, 'data');
+  const layout = new StorageLayout({ dataDir });
+  const projects = new ProjectStore({ layout });
+  const registry = new ProjectRegistryStore({ layout });
+  const vector = await stubVectorServer();
+  const analyzerEvents = [];
+  const engineDataDir = path.join(root, 'engine-data');
+  fs.mkdirSync(engineDataDir, { recursive: true });
+  const engine = createEngineServer({ dataDir: engineDataDir, vectorUrl: vector.url, bridge: forbiddenBridge(), analyzer: stubAnalyzer(analyzerEvents) });
+  await engine.ready;
+  await new Promise(resolve => engine.server.listen(0, '127.0.0.1', resolve));
+  const engineUrl = `http://127.0.0.1:${engine.server.address().port}`;
+  const call = async (route, body) => {
+    const response = await fetch(`${engineUrl}${route}`, {
+      method: body === undefined ? 'GET' : 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    return { status: response.status, body: await response.json() };
+  };
+
+  try {
+    // ---------------------------------------------------------------- fixtures
+    const repoA = fixture.makeRepo(root, 'repo-a', [
+      { message: 'initial', files: { 'README.md': '# A\n\n初始内容\n' } },
+      { message: 'feature', files: { 'feature.txt': 'feature A\n' } },
+    ]);
+    const repoB = fixture.makeRepo(root, 'repo-b', [{ message: 'initial', files: { 'README.md': '# B\n' } }]);
+    const repoC = fixture.makeRepo(root, 'repo-c', [{ message: 'initial', files: { 'README.md': '# C\n' } }]);
+    const knowledgeA = fixture.makeKnowledgeDir(root, 'knowledge-a');
+    const knowledgeB = fixture.makeKnowledgeDir(root, 'knowledge-b');
+    const knowledgeC = fixture.makeKnowledgeDir(root, 'knowledge-c');
+    const promotedEntry = `changes/planted-${repoA.head.slice(0, 12)}.md`;
+    const promotedBody = `# 真实晋升条目\n\nRET001TOKEN 事实：本次提交把配额采样改为串行执行。\n\ncommit: ${repoA.head}\n`;
+    fs.mkdirSync(path.join(knowledgeA, 'changes'), { recursive: true });
+    fs.writeFileSync(path.join(knowledgeA, promotedEntry), promotedBody, 'utf8');
+    fs.writeFileSync(path.join(knowledgeA, 'changes', 'template.md'), '# 模板\n\nTODO: 待补充\n', 'utf8');
+    fs.writeFileSync(path.join(knowledgeB, 'README.md'), '# B\n\nDOMAINONLYTOKEN 属于领域知识\n', 'utf8');
+    fs.writeFileSync(path.join(knowledgeC, 'README.md'), '# C\n\nOTHERDOMAINTOKEN 属于其它领域\n', 'utf8');
+
+    await projects.create('project-a', { displayName: 'A', repoPath: repoA.repoPath, knowledgePath: knowledgeA, relatedProjectIds: ['project-b'], brainId: 'brain-default', domainId: 'domain-tools' });
+    await projects.create('project-b', { displayName: 'B', repoPath: repoB.repoPath, knowledgePath: knowledgeB, brainId: 'brain-default', domainId: 'domain-tools' });
+    await projects.create('project-c', { displayName: 'C', repoPath: repoC.repoPath, knowledgePath: knowledgeC, brainId: 'brain-default', domainId: 'domain-other' });
+    for (const id of ['project-a', 'project-b', 'project-c']) await registry.add(id, { displayNameSnapshot: id });
+
+    // The root product service is the authoritative-Markdown reader used by
+    // the shell. No embedder and no index exist yet.
+    const service = new KnowledgeRetrievalService({ layout, registryStore: registry, projectStore: projects });
+
+    // --------------------------------------------------------------- RET-001
+    {
+      const before = fixture.hashTree(knowledgeA);
+      const response = await service.search({ projectId: 'project-a', query: 'RET001TOKEN' });
+      assert.equal(response.ok, true);
+      assert.ok(response.results.length >= 1, 'the promoted fact must be retrievable');
+      const top = response.results[0];
+      assert.equal(top.entry_id, promotedEntry, 'citation must point at the promoted relative entry');
+      assert.ok(top.chunk_text.includes('RET001TOKEN'), 'the result must carry the real body text');
+      assert.ok(top.chunk_text.includes('配额采样改为串行执行'), 'the returned body must contain the promoted fact sentence');
+      const expectedDocumentHash = sha256(`chunker:${CHUNKER_VERSION}\n${promotedBody}`);
+      assert.equal(top.document_hash, expectedDocumentHash, 'document hash must be recomputable from the real file');
+      assert.equal(top.content_hash, crypto.createHash('sha256').update(top.chunk_text, 'utf8').digest('hex'), 'content hash must match the returned body');
+      assert.ok(!response.results.some(row => /TODO|待补充/.test(row.chunk_text)), 'template placeholders must not be presented as facts');
+      assert.equal(response.backend, 'markdown-hybrid-fallback', 'no vector channel exists in this lane, so the backend must not claim a hybrid hit');
+      assert.notEqual(response.health.index, 'ok');
+      assert.deepEqual(fixture.hashTree(knowledgeA), before, 'retrieval must not mutate knowledge files');
+      record('RET-001', 'PASS', { entryId: top.entry_id, documentHash: top.document_hash, backend: response.backend, healthIndex: response.health.index, resultCount: response.results.length });
+    }
+
+    // --------------------------------------------------------------- RET-003
+    {
+      const projectScope = await service.search({ projectId: 'project-a', query: 'RET001TOKEN' });
+      assert.ok(projectScope.results.every(row => row.scope_project_id === 'project-a' || row.scope_project_id === 'project-b'), 'project scope may only expose the project and its declared related projects');
+      assert.ok(!projectScope.results.some(row => row.chunk_text.includes('OTHERDOMAINTOKEN')), 'an unrelated project must never leak into the project scope');
+      const unrelated = await service.search({ projectId: 'project-c', query: 'OTHERDOMAINTOKEN' });
+      assert.ok(unrelated.results.every(row => row.scope_project_id === 'project-c'));
+      assert.ok(!unrelated.results.some(row => row.chunk_text.includes('RET001TOKEN')), 'another project must not borrow this project context');
+      await assert.rejects(service.search({ projectId: 'project-unknown', query: 'RET001TOKEN' }), 'an unknown project must fail instead of borrowing a registered context');
+
+      // Real engine scope semantics over real loopback HTTP.
+      for (const project of [
+        { projectId: 'project-a', name: 'A', repoPath: repoA.repoPath, knowledgePath: knowledgeA, brainId: 'brain-default', domainId: 'domain-tools' },
+        { projectId: 'project-b', name: 'B', repoPath: repoB.repoPath, knowledgePath: knowledgeB, brainId: 'brain-default', domainId: 'domain-tools' },
+        { projectId: 'project-c', name: 'C', repoPath: repoC.repoPath, knowledgePath: knowledgeC, brainId: 'brain-default', domainId: 'domain-other' },
+      ]) await call('/api/projects', project);
+      fs.writeFileSync(path.join(knowledgeA, 'shared.md'), '# A\n\nSHAREDTOKEN 共享事实 A\n', 'utf8');
+      fs.writeFileSync(path.join(knowledgeB, 'shared.md'), '# B\n\nSHAREDTOKEN 共享事实 B\n', 'utf8');
+      fs.writeFileSync(path.join(knowledgeC, 'shared.md'), '# C\n\nSHAREDTOKEN 共享事实 C\n', 'utf8');
+
+      const projectScopeEngine = await call('/api/search', { projectId: 'project-a', query: 'SHAREDTOKEN', scope: 'project' });
+      assert.equal(projectScopeEngine.status, 200);
+      assert.deepEqual([...new Set(projectScopeEngine.body.results.map(row => row.scope_project_id))], ['project-a'], 'engine project scope must stay inside the project');
+      const domainScopeEngine = await call('/api/search', { projectId: 'project-a', query: 'SHAREDTOKEN', scope: 'domain' });
+      assert.deepEqual([...new Set(domainScopeEngine.body.results.map(row => row.scope_project_id))].sort(), ['project-a', 'project-b'], 'engine domain scope must expose the same-domain project only');
+      const brainScopeEngine = await call('/api/search', { projectId: 'project-a', query: 'SHAREDTOKEN', scope: 'brain' });
+      assert.deepEqual([...new Set(brainScopeEngine.body.results.map(row => row.scope_project_id))].sort(), ['project-a', 'project-b', 'project-c'], 'engine brain scope must expose every project of the brain');
+      const unknownEngine = await call('/api/search', { projectId: 'project-unknown', query: 'SHAREDTOKEN' });
+      assert.equal(unknownEngine.status, 404, 'an unknown project must be refused by the engine');
+      assert.equal(unknownEngine.body.error, 'PROJECT_NOT_FOUND', 'the real engine reports the failure code as a string');
+      const invalidScope = await call('/api/search', { projectId: 'project-a', query: 'SHAREDTOKEN', scope: 'global' });
+      assert.equal(invalidScope.body.error, 'INVALID_ARGUMENT', 'an unknown scope must be refused');
+      record('RET-003', 'PASS', {
+        rootServiceScopes: [...new Set(projectScope.results.map(row => row.scope_project_id))].sort(),
+        engineProjectScope: [...new Set(projectScopeEngine.body.results.map(row => row.scope_project_id))],
+        engineDomainScope: [...new Set(domainScopeEngine.body.results.map(row => row.scope_project_id))].sort(),
+        engineBrainScope: [...new Set(brainScopeEngine.body.results.map(row => row.scope_project_id))].sort(),
+        unknownProjectStatus: unknownEngine.status,
+        vectorStubRequests: vector.requests.length,
+      });
+    }
+
+    // --------------------------------------------------------------- RET-004
+    {
+      // A real promoted run: the engine analyses the real commit SHA and the
+      // promoted file keeps that SHA as its source.
+      const run = engine.coordinator.enqueue({ projectId: 'project-a', commitSha: repoA.head });
+      const promoted = await fixture.eventually(() => engine.store.getRun(run.runId) && ['succeeded', 'failed', 'index-pending'].includes(engine.store.getRun(run.runId).state));
+      assert.equal(promoted, true, 'the run must reach a terminal state');
+      const finished = engine.store.getRun(run.runId);
+      assert.equal(finished.state, 'succeeded', `run failed: ${JSON.stringify(finished.error)}`);
+      const promotedFile = path.join(knowledgeA, `changes/${repoA.head.slice(0, 12)}.md`);
+      assert.ok(fs.existsSync(promotedFile), 'the promoted Markdown must exist on disk');
+      const promotedText = fs.readFileSync(promotedFile, 'utf8');
+      assert.ok(promotedText.includes(repoA.head), 'the promoted body must carry the real commit SHA');
+
+      const search = await call('/api/search', { projectId: 'project-a', query: repoA.head.slice(0, 12) });
+      assert.equal(search.status, 200);
+      const hit = search.body.results.find(row => row.entry_id === `changes/${repoA.head.slice(0, 12)}.md`);
+      assert.ok(hit, 'the promoted entry must be retrievable');
+      assert.equal(hit.commitSha, repoA.head, 'the citation must carry the full commit source of the current result');
+      assert.equal(hit.path, `changes/${repoA.head.slice(0, 12)}.md`, 'the citation path must be relative to the project knowledge root');
+
+      const read = await call('/api/get', { projectId: 'project-a', entryId: hit.entry_id });
+      assert.equal(read.status, 200);
+      assert.ok(read.body.chunks[0].chunk_text.includes(repoA.head), 'reading the citation must return the real body');
+      const outside = await call('/api/get', { projectId: 'project-a', entryId: '../outside.md' });
+      assert.equal(outside.status, 403, 'path traversal must be refused');
+      assert.equal(outside.body.error, 'PATH_OUTSIDE_ROOT', 'the real engine reports the failure code as a string');
+
+      // The product's own client must reach the same real engine.
+      const client = new EngineKnowledgeClient({ layout, engineUrl });
+      const viaClient = await client.request('get', { entry: hit.entry_id }, { projectId: 'project-a', repoPath: repoA.repoPath, knowledgePath: knowledgeA });
+      assert.ok(viaClient.chunks[0].chunk_text.includes(repoA.head));
+      await assert.rejects(client.request('get', { entry: '../outside.md' }, { projectId: 'project-a', repoPath: repoA.repoPath, knowledgePath: knowledgeA }), error => error.code === 'PATH_OUTSIDE_ROOT' && !error.message.includes(repoA.head));
+      await assert.rejects(client.request('search', { query: 'x', scope: 'global' }, { projectId: 'project-a', repoPath: repoA.repoPath, knowledgePath: knowledgeA }), error => error.code === 'INVALID_ARGUMENT');
+      record('RET-004', 'PASS', {
+        promotedEntry: hit.entry_id,
+        commitSha: hit.commitSha,
+        documentHash: hit.document_hash,
+        traversalStatus: outside.status,
+        traversalCode: outside.body.error.code,
+        analyzerStubRuns: analyzerEvents.length,
+      });
+    }
+
+    // --------------------------------------------------------------- RET-005
+    {
+      // The embedding channel is switched off: no embedder, then a failing
+      // embedder. The Markdown truth must still answer, and nothing may claim
+      // a vector success or delete knowledge.
+      const before = fixture.hashTree(knowledgeA);
+      fs.mkdirSync(layout.getIndexPath(), { recursive: true });
+      const disabled = new KnowledgeRetrievalService({ layout, registryStore: registry, projectStore: projects, embedderProvider: () => null });
+      const disabledResponse = await disabled.search({ projectId: 'project-a', query: 'RET001TOKEN' });
+      assert.equal(disabledResponse.backend, 'markdown-hybrid-fallback');
+      assert.equal(disabledResponse.health.index, 'unavailable');
+      assert.ok(disabledResponse.results.length >= 1, 'Markdown truth must stay visible when the embedding channel is off');
+      assert.ok(disabledResponse.results.every(row => !row.match_channels.includes('index:vector-hub')), 'no result may claim a vector channel');
+
+      const failing = new KnowledgeRetrievalService({
+        layout,
+        registryStore: registry,
+        projectStore: projects,
+        // Row-less index: the database refuses every query, so no vector row
+        // can ever reach a result. The only observable effect is the
+        // degradation path of the Markdown truth reader.
+        databaseProvider: () => ({ async hybridSearch() { throw new Error('index offline'); } }),
+        embedderProvider: () => ({ async embedQuery() { throw new Error('embedding disabled'); } }),
+      });
+      const failingResponse = await failing.search({ projectId: 'project-a', query: 'RET001TOKEN' });
+      assert.equal(failingResponse.health.index, 'degraded');
+      assert.equal(failingResponse.health.reason, 'index-query-failed');
+      assert.equal(failingResponse.backend, 'markdown-hybrid-fallback');
+      assert.ok(failingResponse.results.length >= 1, 'a degraded index must still expose the Markdown truth');
+      assert.ok(failingResponse.results.every(row => !row.match_channels.includes('index:vector-hub')));
+      assert.deepEqual(fixture.hashTree(knowledgeA), before, 'a disabled embedding channel must not delete or rewrite knowledge');
+      record('RET-005', 'PASS', {
+        disabledBackend: disabledResponse.backend,
+        disabledHealth: disabledResponse.health.index,
+        degradedHealth: failingResponse.health.index,
+        degradedReason: failingResponse.health.reason,
+        knowledgeFilesUnchanged: true,
+        resultCount: failingResponse.results.length,
+      });
+    }
+
+    const summary = { lane: 'test-knowledge', file: 'parallel-knowledge-retrieval-test.js', cases: results, vectorChannel: 'stubbed-empty-results (not vector evidence)' };
+    const target = process.env.PARALLEL_KNOWLEDGE_EVIDENCE;
+    if (target) fs.mkdirSync(path.dirname(target), { recursive: true });
+    if (target) fs.writeFileSync(target, JSON.stringify(summary, null, 2), 'utf8');
+    console.log('parallel-knowledge-retrieval-test PASS');
+  } finally {
+    await engine.close();
+    await vector.close();
+    fixture.removeTree(root);
+    fixture.cleanupIsolatedProcess();
+  }
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/parallel-knowledge-vector-test.js

@@ -0,0 +1,168 @@
+'use strict';
+// Parallel knowledge lane — canonical vector-side contracts (RET-006 sub-items).
+//
+// Scope: only the deterministic, environment-independent contracts are proven
+// here, because the file is collected by the offline regression runner:
+//   RET-006.a-root-switch            the hub accepts and reports a new index root
+//   RET-006.b-writer-drain            an in-flight writer is drained before the switch resolves
+//   RET-006.c-old-root-retained      the old index root keeps its data byte-for-byte
+//   RET-006.d-project-knowledge-kept  a project knowledge directory is never moved by the switch
+//
+// RET-006 as a whole is NOT claimed to pass here: this file proves the
+// deterministic sub-items a-d only. The remaining sub-item ("新根重建":
+// writing an actual index into the new root) needs a real embedding model,
+// because the hub refuses any index write without one. That
+// environment-dependent acceptance lives in the explicitly invoked probe
+// qa-autopilot/tools/product-probes/parallel-knowledge-vector.js, which now
+// drives a real hub upsert/search, a real root switch, a real rebuild in the
+// new root and a real old-root retention check, and reports RET-002/RET-006
+// as BLOCKED instead of faking a green result.
+//
+// This file performs no model load, no download and no paid API call, and it
+// never touches the live 5757/5790/8787/8790 endpoints.
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const fixture = require('./helpers/parallel-knowledge-fixture');
+// The entry point isolates itself: ambient module addresses, live data
+// directories and the real HOME are cleared here, before anything else loads.
+fixture.isolateProcess();
+
+const results = [];
+function record(caseId, status, detail) {
+  results.push({ caseId, status, detail });
+  console.log(`CASE ${caseId} ${status} ${JSON.stringify(detail)}`);
+}
+
+const HUB_DIST = path.resolve(__dirname, '..', '..', 'node_modules', '@sanqianx', 'vector-hub', 'dist', 'cjs');
+
+(async () => {
+  const root = fixture.makeTempDir('parallel-knowledge-vector');
+  try {
+    const oldRoot = path.join(root, 'indexes-old');
+    const newRoot = path.join(root, 'indexes-new');
+    const configPath = path.join(root, 'vector-hub', 'config.json');
+    fs.mkdirSync(path.join(oldRoot, 'demo'), { recursive: true });
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(path.join(oldRoot, 'demo', 'note.md'), '旧索引根下的真实数据\n', 'utf8');
+    const oldRootBefore = fixture.hashTree(oldRoot);
+    const knowledgePath = fixture.makeKnowledgeDir(root, 'knowledge-index');
+    fs.writeFileSync(path.join(knowledgePath, 'README.md'), '# 索引根切换\n\nRET006TOKEN 项目知识\n', 'utf8');
+    const knowledgeBefore = fixture.hashTree(knowledgePath);
+
+    const port = await fixture.freePort();
+    const token = 'parallel-knowledge-runtime-token';
+    const process_ = fixture.spawnNode([
+      path.join(HUB_DIST, 'bin.js'), 'serve', '--port', String(port), '--root', oldRoot, '--config', configPath,
+    ], {
+      KB_VECTOR_MANAGED: '1',
+      KB_VECTOR_RUNTIME_TOKEN: token,
+      VECTOR_HUB_DISABLE_PICKER: '1',
+      VECTOR_HUB_ROOT: oldRoot,
+      VECTOR_HUB_CONFIG: configPath,
+      MINIMAX_API_KEY: '',
+    });
+    try {
+      const base = `http://127.0.0.1:${port}`;
+      fixture.assertAllowedEndpoint(base, 'vector hub');
+      await fixture.waitForHttp(`${base}/api/projects`, 20000);
+      const before = await (await fetch(`${base}/api/projects`)).json();
+      assert.ok(before.projects.length >= 0);
+
+      // The real switch: the shell posts the new absolute index root.
+      const switched = await fetch(`${base}/api/internal/runtime-config`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+        body: JSON.stringify({ settings: null, storageRoot: newRoot }),
+      });
+      const switchedText = await switched.text();
+      assert.equal(switched.status, 200, `runtime-config switch failed: ${switched.status} ${switchedText}`);
+      const switchedBody = JSON.parse(switchedText);
+
+      // ---- RET-006.a-root-switch
+      assert.equal(switchedBody.rootPath, path.resolve(newRoot), 'the hub must report the new index root');
+      assert.ok(fs.existsSync(newRoot), 'the new index root must be created');
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+      assert.equal(path.resolve(config.settings.rootPath), path.resolve(newRoot), 'the persisted configuration must point at the new root');
+      const after = await (await fetch(`${base}/api/projects`)).json();
+      assert.ok(Array.isArray(after.projects));
+      record('RET-006.a-root-switch', 'PASS', {
+        port,
+        reportedRootPath: switchedBody.rootPath,
+        persistedRoot: config.settings.rootPath,
+        newRootCreated: fs.existsSync(newRoot),
+      });
+
+      // ---- RET-006.c-old-root-retained
+      assert.deepEqual(fixture.hashTree(oldRoot), oldRootBefore, 'the old index root data must be retained byte-for-byte');
+      record('RET-006.c-old-root-retained', 'PASS', {
+        oldRoot: path.resolve(oldRoot),
+        oldRootRetained: JSON.stringify(fixture.hashTree(oldRoot)) === JSON.stringify(oldRootBefore),
+        oldRootStillExists: fs.existsSync(oldRoot),
+      });
+
+      // ---- RET-006.d-project-knowledge-kept
+      assert.deepEqual(fixture.hashTree(knowledgePath), knowledgeBefore, 'the project knowledge must not be moved by an index root switch');
+      record('RET-006.d-project-knowledge-kept', 'PASS', {
+        knowledgePath: path.resolve(knowledgePath),
+        projectKnowledgeUnchanged: JSON.stringify(fixture.hashTree(knowledgePath)) === JSON.stringify(knowledgeBefore),
+      });
+
+      // ---- RET-006.b-writer-drain
+      // The drain barrier, measured on the real HubManager: a real project
+      // write that is still running must finish before the root switch
+      // resolves.
+      const { HubManager } = require(path.join(HUB_DIST, 'server', 'manager.js'));
+      const drainOldRoot = path.join(root, 'drain-old');
+      const drainNewRoot = path.join(root, 'drain-new');
+      const drainConfig = path.join(root, 'drain', 'config.json');
+      fs.mkdirSync(drainOldRoot, { recursive: true });
+      fs.mkdirSync(path.dirname(drainConfig), { recursive: true });
+      const manager = await HubManager.load({ rootPath: drainOldRoot, configPath: drainConfig, managed: true });
+      const order = {};
+      const write = manager.withProjectWrite('demo', async () => {
+        await new Promise(resolve => setTimeout(resolve, 600));
+        order.writeFinished = Date.now();
+        return 'written';
+      });
+      await new Promise(resolve => setTimeout(resolve, 50));
+      const switchStart = Date.now();
+      await manager.applyRuntimeSettings(null, drainNewRoot);
+      order.switchFinished = Date.now();
+      order.switchStart = switchStart;
+      await write;
+      assert.ok(order.writeFinished, 'the in-flight write must have finished');
+      assert.ok(order.writeFinished <= order.switchFinished, 'the root switch must wait for the old writer to drain');
+      assert.ok(order.switchFinished - switchStart >= 400, 'the root switch must not resolve before the pending write completes');
+      assert.equal(path.resolve(manager.hub.rootPath), path.resolve(drainNewRoot), 'the manager must point at the new root after the switch');
+      assert.ok(fs.existsSync(drainOldRoot), 'the drained root must still exist');
+      record('RET-006.b-writer-drain', 'PASS', {
+        switchWaitedForWriter: order.switchFinished - order.switchStart,
+        writerFinishedBeforeSwitch: order.writeFinished <= order.switchFinished,
+        managerRootAfterSwitch: path.resolve(manager.hub.rootPath),
+        drainedRootStillExists: fs.existsSync(drainOldRoot),
+      });
+    } finally {
+      process_.child.kill();
+      await process_.exited;
+    }
+
+    const summary = {
+      lane: 'test-knowledge',
+      file: 'parallel-knowledge-vector-test.js',
+      cases: results,
+      ret006Overall: 'PARTIAL',
+      ret006ScopeHere: 'a-d only: this file proves the deterministic, environment-independent sub-items of RET-006 and nothing more.',
+      ret006NotExercisedHere: '新根重建（向新根写入真实索引）需要真实 embedding 模型，hub 在未配置模型时拒绝任何索引写入；该环境依赖验收在显式调用的 probe qa-autopilot/tools/product-probes/parallel-knowledge-vector.js 中判定——该 probe 已实现真实 hub upsert/search、根切换、新根重建检索与旧根保留，未取得模型时记 BLOCKED。',
+      vectorChannel: 'no index content was written: the environment has no authorised embedding model, so only the deterministic storage-root contracts are proven here',
+      probe: 'qa-autopilot/tools/product-probes/parallel-knowledge-vector.js',
+    };
+    const target = process.env.PARALLEL_KNOWLEDGE_EVIDENCE;
+    if (target) fs.mkdirSync(path.dirname(target), { recursive: true });
+    if (target) fs.writeFileSync(target, JSON.stringify(summary, null, 2), 'utf8');
+    console.log('parallel-knowledge-vector-test PASS (RET-006 sub-items a-d only; the new-root rebuild is covered by the tracked probe, not here)');
+  } finally {
+    fixture.removeTree(root);
+    fixture.cleanupIsolatedProcess();
+  }
+})().catch(error => { console.error(error); process.exitCode = 1; });

package/_site/_test/parallel-linux-ci-r7-log007-day-test.js

@@ -0,0 +1,110 @@
+'use strict';
+// P-LINUX-CI-CLOSEOUT-R7 focused case: the log007 day-filter contract, pinned
+// deterministically OFFLINE (real Logger + real LogRepository; no server, no
+// browser, no clock race).
+//
+// CI shape reproduced (run 40062048045, linux22+24, log007
+// timeDayGranularity=false while every other filter stayed green): the live
+// server writes a project-scoped bridge_consumer.identity_backfilled record
+// into the same local-day file ~0.2-1s after health, so the old
+// count === 4 day-window expectation raced the server's own async startup
+// write and lost on the Linux boot timing (Windows CI landed it after the
+// queries). Here the same five-record shape is built with the real logger and
+// the record-anchored contract is asserted: all four fixture records appear in
+// their day's window, and EVERY entry of a from=X&to=X window carries
+// localDay(ts) === X.
+//
+// Day-boundary contract: records with explicit timestamps one millisecond
+// either side of a UTC midnight keep whatever local days the machine's zone
+// assigns; the windows derived from the records themselves return exactly the
+// records dated inside them (file-day naming and matches-day must agree in
+// any zone — the property the old now/now±24h window construction could not
+// guarantee).
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const assert = require('node:assert/strict');
+
+const { installLoggingTestEnv, resolveEvidenceDir } = require('./helpers/parallel-logging-integration-5025-env');
+const lane = installLoggingTestEnv({ caseId: 'LINUX-CI-R7-LOG007-DAY', prefix: 'lcr7day' });
+
+const { Logger, LogRepository, localDay } = require('../lib/structured-logger');
+const { StorageLayout } = require('../lib/storage-layout');
+
+const ROOT = path.resolve(__dirname, '../..');
+const ARTIFACTS = resolveEvidenceDir(path.resolve(ROOT, 'qa-autopilot/artifacts/parallel-20261023/linux-ci-closeout-r7/evidence/log007-day'));
+const PROJECT = 'project-lcr7-day';
+
+const shiftDay = (day, delta) => new Date(Date.UTC(Number(day.slice(0, 4)), Number(day.slice(5, 7)) - 1, Number(day.slice(8, 10)) + delta)).toISOString().slice(0, 10);
+
+(async () => {
+  fs.mkdirSync(ARTIFACTS, { recursive: true });
+  const evidence = { caseId: 'LINUX-CI-R7-LOG007-DAY', startedAt: new Date().toISOString(), platform: process.platform };
+  const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pk-r7-day-'));
+  const layout = new StorageLayout({ dataDir });
+  const settings = { levels: ['trace', 'debug', 'info', 'warn', 'error', 'fatal'] };
+  const logger = new Logger({ layout, settingsProvider: () => settings });
+  const repository = new LogRepository({ layout });
+  try {
+    // --- 1. the CI five-record shape ------------------------------------
+    const baseTs = new Date().toISOString();
+    const fixtureEvents = ['lcr7.early.info', 'lcr7.early.warn', 'lcr7.late.warn', 'lcr7.late.error'];
+    for (const [index, event] of fixtureEvents.entries()) {
+      await logger.log(index === 3 ? 'error' : index === 0 ? 'info' : 'warn', event, `LCR7 ${event}`, { ts: baseTs, projectId: PROJECT, component: `lcr7-comp-${'abc'[index % 3]}` });
+    }
+    // The server's own startup record: project-scoped, same day, written by
+    // the same real logger path.
+    await logger.log('info', 'bridge_consumer.identity_backfilled', 'identity backfilled', { ts: baseTs, projectId: PROJECT, component: 'bridge-consumer' });
+
+    const day = localDay(baseTs);
+    const window = await repository.query({ projectId: PROJECT, from: day, to: day, pageSize: 100 });
+    const events = window.entries.map(entry => entry.event).sort();
+    const oldExpectationHeld = window.entries.length === 4;
+    assert.equal(window.entries.length, 5, 'the CI shape holds five same-day project records, not four');
+    assert.equal(oldExpectationHeld, false, 'the old count === 4 day-window expectation is exactly what failed on CI');
+    for (const event of fixtureEvents) assert.ok(events.includes(event), `fixture record ${event} must appear in its day window`);
+    for (const entry of window.entries) assert.equal(localDay(entry.ts), day, `every from=X&to=X entry must be dated X (${entry.event})`);
+    const next = await repository.query({ projectId: PROJECT, from: shiftDay(day, 1), to: shiftDay(day, 1), pageSize: 100 });
+    const prev = await repository.query({ projectId: PROJECT, from: shiftDay(day, -1), to: shiftDay(day, -1), pageSize: 100 });
+    assert.equal(next.entries.length, 0, 'the next-day window is empty for same-day records');
+    assert.equal(prev.entries.length, 0, 'the previous-day window is empty for same-day records');
+    evidence.ciShape = { day, count: window.entries.length, events, oldCountFourWouldFail: true };
+
+    // --- 2. day-boundary records in whatever zone the machine runs ------
+    const beforeMidnight = '2026-01-01T23:59:59.999Z';
+    const afterMidnight = '2026-01-02T00:00:00.001Z';
+    await logger.log('info', 'lcr7.boundary.before', 'boundary before', { ts: beforeMidnight, projectId: PROJECT, component: 'lcr7-boundary' });
+    await logger.log('info', 'lcr7.boundary.after', 'boundary after', { ts: afterMidnight, projectId: PROJECT, component: 'lcr7-boundary' });
+    const dayBefore = localDay(beforeMidnight);
+    const dayAfter = localDay(afterMidnight);
+    const windowBefore = await repository.query({ projectId: PROJECT, component: 'lcr7-boundary', from: dayBefore, to: dayBefore, pageSize: 100 });
+    const windowAfter = await repository.query({ projectId: PROJECT, component: 'lcr7-boundary', from: dayAfter, to: dayAfter, pageSize: 100 });
+    assert.ok(windowBefore.entries.some(entry => entry.event === 'lcr7.boundary.before'), 'the pre-midnight record is in its own local-day window');
+    assert.ok(windowAfter.entries.some(entry => entry.event === 'lcr7.boundary.after'), 'the post-midnight record is in its own local-day window');
+    assert.equal(windowBefore.entries.some(entry => entry.event === 'lcr7.boundary.after'), dayBefore === dayAfter,
+      'the post-midnight record appears in the pre-midnight window only when the zone maps both timestamps to one local day');
+    for (const entry of windowBefore.entries) assert.equal(localDay(entry.ts), dayBefore, `boundary window entry dated outside the window (${entry.event})`);
+    for (const entry of windowAfter.entries) assert.equal(localDay(entry.ts), dayAfter, `boundary window entry dated outside the window (${entry.event})`);
+    evidence.dayBoundary = { zoneOffsetMinutes: new Date().getTimezoneOffset(), dayBefore, dayAfter, sameLocalDay: dayBefore === dayAfter };
+
+    // --- 3. the day-string arithmetic the driver now uses ---------------
+    assert.equal(shiftDay('2026-01-01', -1), '2025-12-31', 'previous day crosses the year boundary');
+    assert.equal(shiftDay('2026-02-28', 1), '2026-03-01', 'next day crosses the non-leap February boundary');
+    assert.equal(shiftDay('2026-10-24', 1), '2026-10-25', 'next day of the CI failure date');
+    assert.equal(shiftDay('2026-10-24', -1), '2026-10-23', 'previous day of the CI failure date');
+    evidence.shiftDay = { yearBoundary: true, februaryBoundary: true };
+
+    evidence.verdict = 'PASS — five-record CI shape returns all four fixture records with every window entry correctly dated (old count===4 expectation reproduced as false); UTC-millisecond boundary records land in their zone-assigned local-day windows; day-string arithmetic is boundary-correct';
+  } finally {
+    evidence.finishedAt = new Date().toISOString();
+    fs.writeFileSync(path.join(ARTIFACTS, 'log007-day-evidence.json'), JSON.stringify(evidence, null, 2) + '\n', 'utf8');
+    fs.rmSync(dataDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+    lane.cleanup();
+  }
+  console.log('LINUX-CI-R7 LOG-007 DAY PASS');
+  process.exitCode = 0;
+})().catch(error => {
+  console.error(`LINUX-CI-R7 LOG-007 DAY FAIL: ${error.message}`);
+  process.exitCode = 1;
+});