@sanqianx/project-knowledge 5.0.24 → 5.0.25

package/_site/_test/tracking-start-test.js

@@ -1,144 +1,144 @@
-// Run: node _site/_test/tracking-start-test.js
-
-const assert = require('assert');
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const { spawnSync } = require('child_process');
-const { StorageLayout } = require('../lib/storage-layout');
-const { ProjectRegistryStore } = require('../lib/project-registry-store');
-const { ProjectStore } = require('../lib/project-store');
-const { ProjectLifecycleService } = require('../lib/project-lifecycle-service');
-const { CommitReconciler } = require('../lib/commit-reconciler');
-
-const temp = fs.mkdtempSync(path.join(os.tmpdir(), `kb-tracking-start-${process.pid}-`));
-const layout = new StorageLayout({ dataDir: path.join(temp, 'data') });
-const registry = new ProjectRegistryStore({ layout });
-const projects = new ProjectStore({ layout });
-const knowledgeRoot = path.join(temp, 'knowledge');
-
-function git(repo, args) {
-  const result = spawnSync('git', ['-C', repo, ...args], { encoding: 'utf8', windowsHide: true });
-  if (result.status !== 0) throw new Error(result.stderr || `git ${args.join(' ')} failed`);
-  return String(result.stdout || '').trim();
-}
-
-function repo(name, withCommit) {
-  const target = path.join(temp, name);
-  fs.mkdirSync(target, { recursive: true });
-  git(target, ['init', '--initial-branch=main']);
-  git(target, ['config', 'user.email', 'tracking@example.test']);
-  git(target, ['config', 'user.name', 'Tracking Test']);
-  if (withCommit) commit(target, 'imported');
-  return target;
-}
-
-function commit(target, name) {
-  fs.writeFileSync(path.join(target, `${name}.txt`), `${name}\n`, 'utf8');
-  git(target, ['add', `${name}.txt`]);
-  git(target, ['commit', '-m', name]);
-  return git(target, ['rev-parse', 'HEAD']);
-}
-
-(async () => {
-  fs.mkdirSync(knowledgeRoot, { recursive: true });
-  await registry.initialize();
-  const installed = [];
-  const lifecycle = new ProjectLifecycleService({
-    layout,
-    registryStore: registry,
-    projectStore: projects,
-    settingsStore: { read: () => ({ knowledge: { rootPath: knowledgeRoot }, ai: { schema: 'ai-profiles/v1', profiles: [{ id: 'test-profile', enabled: true, vendor: 'anthropic', model: 'm' }], defaultProfileId: null } }) },
-    triggerScriptPath: path.join(temp, 'hook-trigger.js'),
-    hookManager: {
-      readHookStatus: () => ({ kbManaged: false }),
-      installHook: options => { installed.push(options.projectId); return { ok: true, managedVersion: 2 }; },
-      uninstallHook: () => ({ ok: true }),
-    },
-  });
-
-  const existingRepo = repo('existing-repo', true);
-  const importedHead = git(existingRepo, ['rev-parse', 'HEAD']);
-  const imported = await lifecycle.importProject({ localPath: existingRepo, projectId: 'project-existing', aiProfileId: 'test-profile' });
-  assert.strictEqual(imported.state.trackingStartCommit, importedHead);
-  assert.strictEqual(imported.state.lastAnalyzedCommit, null);
-  assert.strictEqual(imported.state.trackingMode, 'normal');
-  assert.strictEqual(installed.length, 1, 'import should install Hook but not analyze');
-
-  let processorCalls = 0;
-  const processor = {
-    processClaim: async input => {
-      processorCalls += 1;
-      await projects.updateState(input.projectId, state => {
-        state.lastAnalyzedCommit = input.claim.commitSha;
-        state.analysis.activeClaim = null;
-        state.analysis.status = 'state.advanced';
-        state.index.dirty = true;
-        state.index.generation += 1;
-      });
-      return { stateAdvanced: true };
-    },
-  };
-  const reconciler = new CommitReconciler({
-    layout,
-    registryStore: registry,
-    projectStore: projects,
-    settingsStore: { read: () => ({ knowledge: { rootPath: knowledgeRoot }, ai: { schema: 'ai-profiles/v1', profiles: [{ id: 'test-profile', enabled: true, vendor: 'anthropic', model: 'm' }], defaultProfileId: null } }) },
-    claimProcessor: processor,
-  });
-  await assert.rejects(reconciler.reconcile('project-existing', 'startup'), error => error.code === 'INVALID_TRIGGER');
-  assert.strictEqual(processorCalls, 0, 'startup after import must not analyze pre-import history');
-  const nextCommit = commit(existingRepo, 'after-import');
-  const laterCommit = commit(existingRepo, 'after-import-later');
-  await reconciler.processCommitEvent({ projectId: 'project-existing', commitSha: nextCommit, branch: 'main' });
-  assert.strictEqual(projects.readState('project-existing').lastAnalyzedCommit, nextCommit);
-  assert.strictEqual(processorCalls, 1);
-  await reconciler.processCommitEvent({ projectId: 'project-existing', commitSha: laterCommit, branch: 'main' });
-  assert.strictEqual(projects.readState('project-existing').lastAnalyzedCommit, laterCommit, 'an event SHA remains valid even after HEAD advances');
-  assert.strictEqual(processorCalls, 2);
-
-  const terminalFailedCommit = 'a'.repeat(40);
-  await projects.updateState('project-existing', state => {
-    state.analysis.activeClaim = {
-      schema: 'commit-claim/v1', projectId: 'project-existing', commitSha: terminalFailedCommit, parents: [], requirementIds: [], requirementBinding: 'unavailable',
-      promptTemplateVersion: 'v1', promptHash: 'prompt', patchHash: 'patch', evidenceHash: 'evidence', evidenceManifestHash: 'manifest', retrievalManifestHash: 'retrieval', knowledgePath: knowledgeRoot,
-      runId: 'failed-run', operationId: 'failed-operation', phase: 'failed', attempt: 1, fingerprint: 'failed-fingerprint', error: { code: 'EPERM', retryable: false },
-    };
-    state.analysis.status = 'failed';
-  });
-  const explicitAfterFailure = commit(existingRepo, 'after-terminal-failure');
-  await reconciler.processCommitEvent({ projectId: 'project-existing', commitSha: explicitAfterFailure, branch: 'main' });
-  assert.strictEqual(projects.readState('project-existing').lastAnalyzedCommit, explicitAfterFailure, 'only the new explicit Hook SHA may proceed after a terminal failure');
-  assert.strictEqual(processorCalls, 3, 'terminal failed claims must not retry their old SHA');
-
-  const retryableFailedCommit = 'b'.repeat(40);
-  await projects.updateState('project-existing', state => {
-    state.analysis.activeClaim = {
-      schema: 'commit-claim/v1', projectId: 'project-existing', commitSha: retryableFailedCommit, parents: [], requirementIds: [], requirementBinding: 'unavailable',
-      promptTemplateVersion: 'v1', promptHash: 'prompt', patchHash: 'patch', evidenceHash: 'evidence', evidenceManifestHash: 'manifest', retrievalManifestHash: 'retrieval', knowledgePath: knowledgeRoot,
-      runId: 'retryable-run', operationId: 'retryable-operation', phase: 'failed', attempt: 1, fingerprint: 'retryable-fingerprint', error: { code: 'EAGAIN', retryable: true },
-    };
-    state.analysis.status = 'failed';
-  });
-  const blockedByRetryable = commit(existingRepo, 'after-retryable-failure');
-  const blockedResult = await reconciler.processCommitEvent({ projectId: 'project-existing', commitSha: blockedByRetryable, branch: 'main' });
-  assert.strictEqual(blockedResult.status, 'failed');
-  assert.strictEqual(processorCalls, 3, 'retryable claims must remain blocked instead of being silently superseded');
-  assert.strictEqual(projects.readState('project-existing').analysis.activeClaim.commitSha, retryableFailedCommit);
-
-  const emptyRepo = repo('empty-repo', false);
-  const emptyImported = await lifecycle.importProject({ localPath: emptyRepo, projectId: 'project-empty', aiProfileId: 'test-profile' });
-  assert.strictEqual(emptyImported.state.trackingMode, 'empty-repo');
-  assert.strictEqual(emptyImported.state.trackingStartCommit, null);
-  const firstCommit = commit(emptyRepo, 'first');
-  await reconciler.processCommitEvent({ projectId: 'project-empty', commitSha: firstCommit, branch: 'main' });
-  assert.strictEqual(projects.readState('project-empty').lastAnalyzedCommit, firstCommit, 'first commit after empty import must be analyzed');
-  assert.strictEqual(processorCalls, 4);
-
-  console.log('tracking-start-test PASS');
-})().catch(error => {
-  console.error(error.stack || error.message);
-  process.exitCode = 1;
-}).finally(() => {
-  fs.rmSync(temp, { recursive: true, force: true });
-});
+// Run: node _site/_test/tracking-start-test.js
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { StorageLayout } = require('../lib/storage-layout');
+const { ProjectRegistryStore } = require('../lib/project-registry-store');
+const { ProjectStore } = require('../lib/project-store');
+const { ProjectLifecycleService } = require('../lib/project-lifecycle-service');
+const { CommitReconciler } = require('../lib/commit-reconciler');
+
+const temp = fs.mkdtempSync(path.join(os.tmpdir(), `kb-tracking-start-${process.pid}-`));
+const layout = new StorageLayout({ dataDir: path.join(temp, 'data') });
+const registry = new ProjectRegistryStore({ layout });
+const projects = new ProjectStore({ layout });
+const knowledgeRoot = path.join(temp, 'knowledge');
+
+function git(repo, args) {
+  const result = spawnSync('git', ['-C', repo, ...args], { encoding: 'utf8', windowsHide: true });
+  if (result.status !== 0) throw new Error(result.stderr || `git ${args.join(' ')} failed`);
+  return String(result.stdout || '').trim();
+}
+
+function repo(name, withCommit) {
+  const target = path.join(temp, name);
+  fs.mkdirSync(target, { recursive: true });
+  git(target, ['init', '--initial-branch=main']);
+  git(target, ['config', 'user.email', 'tracking@example.test']);
+  git(target, ['config', 'user.name', 'Tracking Test']);
+  if (withCommit) commit(target, 'imported');
+  return target;
+}
+
+function commit(target, name) {
+  fs.writeFileSync(path.join(target, `${name}.txt`), `${name}\n`, 'utf8');
+  git(target, ['add', `${name}.txt`]);
+  git(target, ['commit', '-m', name]);
+  return git(target, ['rev-parse', 'HEAD']);
+}
+
+(async () => {
+  fs.mkdirSync(knowledgeRoot, { recursive: true });
+  await registry.initialize();
+  const installed = [];
+  const lifecycle = new ProjectLifecycleService({
+    layout,
+    registryStore: registry,
+    projectStore: projects,
+    settingsStore: { read: () => ({ knowledge: { rootPath: knowledgeRoot }, ai: { schema: 'ai-profiles/v1', profiles: [{ id: 'test-profile', enabled: true, vendor: 'anthropic', model: 'm' }], defaultProfileId: null } }) },
+    triggerScriptPath: path.join(temp, 'hook-trigger.js'),
+    hookManager: {
+      readHookStatus: () => ({ kbManaged: false }),
+      installHook: options => { installed.push(options.projectId); return { ok: true, managedVersion: 2 }; },
+      uninstallHook: () => ({ ok: true }),
+    },
+  });
+
+  const existingRepo = repo('existing-repo', true);
+  const importedHead = git(existingRepo, ['rev-parse', 'HEAD']);
+  const imported = await lifecycle.importProject({ localPath: existingRepo, projectId: 'project-existing', aiProfileId: 'test-profile' });
+  assert.strictEqual(imported.state.trackingStartCommit, importedHead);
+  assert.strictEqual(imported.state.lastAnalyzedCommit, null);
+  assert.strictEqual(imported.state.trackingMode, 'normal');
+  assert.strictEqual(installed.length, 1, 'import should install Hook but not analyze');
+
+  let processorCalls = 0;
+  const processor = {
+    processClaim: async input => {
+      processorCalls += 1;
+      await projects.updateState(input.projectId, state => {
+        state.lastAnalyzedCommit = input.claim.commitSha;
+        state.analysis.activeClaim = null;
+        state.analysis.status = 'state.advanced';
+        state.index.dirty = true;
+        state.index.generation += 1;
+      });
+      return { stateAdvanced: true };
+    },
+  };
+  const reconciler = new CommitReconciler({
+    layout,
+    registryStore: registry,
+    projectStore: projects,
+    settingsStore: { read: () => ({ knowledge: { rootPath: knowledgeRoot }, ai: { schema: 'ai-profiles/v1', profiles: [{ id: 'test-profile', enabled: true, vendor: 'anthropic', model: 'm' }], defaultProfileId: null } }) },
+    claimProcessor: processor,
+  });
+  await assert.rejects(reconciler.reconcile('project-existing', 'startup'), error => error.code === 'INVALID_TRIGGER');
+  assert.strictEqual(processorCalls, 0, 'startup after import must not analyze pre-import history');
+  const nextCommit = commit(existingRepo, 'after-import');
+  const laterCommit = commit(existingRepo, 'after-import-later');
+  await reconciler.processCommitEvent({ projectId: 'project-existing', commitSha: nextCommit, branch: 'main' });
+  assert.strictEqual(projects.readState('project-existing').lastAnalyzedCommit, nextCommit);
+  assert.strictEqual(processorCalls, 1);
+  await reconciler.processCommitEvent({ projectId: 'project-existing', commitSha: laterCommit, branch: 'main' });
+  assert.strictEqual(projects.readState('project-existing').lastAnalyzedCommit, laterCommit, 'an event SHA remains valid even after HEAD advances');
+  assert.strictEqual(processorCalls, 2);
+
+  const terminalFailedCommit = 'a'.repeat(40);
+  await projects.updateState('project-existing', state => {
+    state.analysis.activeClaim = {
+      schema: 'commit-claim/v1', projectId: 'project-existing', commitSha: terminalFailedCommit, parents: [], requirementIds: [], requirementBinding: 'unavailable',
+      promptTemplateVersion: 'v1', promptHash: 'prompt', patchHash: 'patch', evidenceHash: 'evidence', evidenceManifestHash: 'manifest', retrievalManifestHash: 'retrieval', knowledgePath: knowledgeRoot,
+      runId: 'failed-run', operationId: 'failed-operation', phase: 'failed', attempt: 1, fingerprint: 'failed-fingerprint', error: { code: 'EPERM', retryable: false },
+    };
+    state.analysis.status = 'failed';
+  });
+  const explicitAfterFailure = commit(existingRepo, 'after-terminal-failure');
+  await reconciler.processCommitEvent({ projectId: 'project-existing', commitSha: explicitAfterFailure, branch: 'main' });
+  assert.strictEqual(projects.readState('project-existing').lastAnalyzedCommit, explicitAfterFailure, 'only the new explicit Hook SHA may proceed after a terminal failure');
+  assert.strictEqual(processorCalls, 3, 'terminal failed claims must not retry their old SHA');
+
+  const retryableFailedCommit = 'b'.repeat(40);
+  await projects.updateState('project-existing', state => {
+    state.analysis.activeClaim = {
+      schema: 'commit-claim/v1', projectId: 'project-existing', commitSha: retryableFailedCommit, parents: [], requirementIds: [], requirementBinding: 'unavailable',
+      promptTemplateVersion: 'v1', promptHash: 'prompt', patchHash: 'patch', evidenceHash: 'evidence', evidenceManifestHash: 'manifest', retrievalManifestHash: 'retrieval', knowledgePath: knowledgeRoot,
+      runId: 'retryable-run', operationId: 'retryable-operation', phase: 'failed', attempt: 1, fingerprint: 'retryable-fingerprint', error: { code: 'EAGAIN', retryable: true },
+    };
+    state.analysis.status = 'failed';
+  });
+  const blockedByRetryable = commit(existingRepo, 'after-retryable-failure');
+  const blockedResult = await reconciler.processCommitEvent({ projectId: 'project-existing', commitSha: blockedByRetryable, branch: 'main' });
+  assert.strictEqual(blockedResult.status, 'failed');
+  assert.strictEqual(processorCalls, 3, 'retryable claims must remain blocked instead of being silently superseded');
+  assert.strictEqual(projects.readState('project-existing').analysis.activeClaim.commitSha, retryableFailedCommit);
+
+  const emptyRepo = repo('empty-repo', false);
+  const emptyImported = await lifecycle.importProject({ localPath: emptyRepo, projectId: 'project-empty', aiProfileId: 'test-profile' });
+  assert.strictEqual(emptyImported.state.trackingMode, 'empty-repo');
+  assert.strictEqual(emptyImported.state.trackingStartCommit, null);
+  const firstCommit = commit(emptyRepo, 'first');
+  await reconciler.processCommitEvent({ projectId: 'project-empty', commitSha: firstCommit, branch: 'main' });
+  assert.strictEqual(projects.readState('project-empty').lastAnalyzedCommit, firstCommit, 'first commit after empty import must be analyzed');
+  assert.strictEqual(processorCalls, 4);
+
+  console.log('tracking-start-test PASS');
+})().catch(error => {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+}).finally(() => {
+  fs.rmSync(temp, { recursive: true, force: true });
+});

package/_site/_test/vector-storage-root-test.js

@@ -1,75 +1,75 @@
-'use strict';
-const assert = require('node:assert/strict');
-const path = require('node:path');
-const { StorageLayout } = require('../lib/storage-layout');
-const { ModuleBridge } = require('../lib/module-bridge');
-const { KnowledgeToolRuntime } = require('../lib/knowledge-tool-runtime');
-const root = path.resolve('D:/knowledge storage 中文');
-const layout = new StorageLayout({ dataDir: path.resolve('D:/metadata') });
-assert.equal(layout.getVectorRootPath({ knowledge: { rootPath: root } }), path.join(root, '.indexes'));
-assert.equal(layout.getVectorRootPath({ knowledge: { rootPath: '' } }), path.join(layout.getDataDir(), 'vectorhub'));
-const settingsStore = { read: () => ({ knowledge: { rootPath: root }, brain: { id: 'brain-default', domains: [] } }) };
-let knowledgeRoot = root;
-const tools = new KnowledgeToolRuntime({
-  layout,
-  settingsStore: { read: () => ({ knowledge: { rootPath: knowledgeRoot } }) },
-  registryStore: { listIds: () => ['project-storage'] },
-  projectStore: {
-    readConfig: () => ({ displayName: 'Storage', repoPath: path.join(root, 'repo'), knowledgePath: path.join(root, 'project') }),
-    readState: () => ({ index: { generation: 3 } }),
-  },
-});
-assert.equal(tools.resolveProject({ projectId: 'project-storage' }).indexPath, path.join(root, '.indexes'), 'MCP/CLI resolution must report the vector-hub location, not the retired shell database');
-knowledgeRoot = path.join(root, 'changed root');
-assert.equal(tools.resolveProject({ projectId: 'project-storage' }).indexPath, path.join(knowledgeRoot, '.indexes'), 'a running MCP process must reread the selected knowledge root');
-knowledgeRoot = '';
-assert.equal(tools.resolveProject({ projectId: 'project-storage' }).indexPath, path.join(layout.getDataDir(), 'vectorhub'));
-const bridge = new ModuleBridge({ settingsStore, dataDir: layout.getDataDir() });
-// The supervisor refuses to spawn the vendored vector-hub on Node < 22
-// (module-bridge: "vector-hub declares engines >= 22"), so its supervised
-// spec — and these env assertions — only exist on qualifying runtimes.
-const vectorHubSpec = bridge._supervisedSpecs().find(spec => spec.name === 'vector-hub');
-if (parseInt(process.versions.node, 10) >= 22) {
-  assert.equal(vectorHubSpec.env.VECTOR_HUB_ROOT, path.join(root, '.indexes'));
-  assert.equal(vectorHubSpec.env.VECTOR_HUB_CONFIG, path.join(layout.getDataDir(), 'vectorhub', 'config.json'));
-} else {
-  assert.equal(vectorHubSpec, undefined, 'vector-hub must not be supervised on Node < 22');
-}
-const calls = [];
-bridge._fetch = async (url, init) => { const body = JSON.parse(init.body); calls.push({ url, body }); return { ok: true, json: async () => url.includes('/api/internal/runtime-config') ? { ok: true, rootPath: path.join(root, '.indexes') } : {} }; };
-bridge.syncEngineConfiguration().then(async status => {
-  assert.equal(calls.find(call => call.url.includes('/api/internal/runtime-config')).body.storageRoot, path.join(root, '.indexes'));
-  assert.equal(status.indexStorage.status, 'ready');
-  let currentRoot = root, release, started;
-  const entered = new Promise(resolve => { started = resolve; });
-  const held = new Promise(resolve => { release = resolve; });
-  const queued = new ModuleBridge({ dataDir: layout.getDataDir(), settingsStore: { read: () => ({ knowledge: { rootPath: currentRoot }, brain: { id: 'brain-default', domains: [] } }) } });
-  const applied = [];
-  queued._fetch = async (url, init) => {
-    const body = JSON.parse(init.body);
-    if (url.endsWith('/api/internal/runtime-config')) {
-      applied.push(body.storageRoot);
-      if (applied.length === 1) { started(); await held; }
-      return { ok: true, json: async () => ({ rootPath: body.storageRoot }) };
-    }
-    return { ok: true, json: async () => null };
-  };
-  const first = queued.syncEngineConfiguration(); await entered;
-  currentRoot = path.join(root, 'new root');
-  const second = queued.syncEngineConfiguration(); release();
-  await first;
-  const latest = await second;
-  assert.deepEqual(applied, [path.join(root, '.indexes'), path.join(currentRoot, '.indexes')]);
-  assert.equal(latest.indexStorage.actualPath, path.join(currentRoot, '.indexes'));
-  assert.equal(latest.indexStorage.status, 'ready');
-  const broken = new ModuleBridge({ dataDir: layout.getDataDir(), settingsStore: { read: () => { throw new Error('corrupt settings'); } } });
-  let revoked;
-  broken._fetch = async (url, init) => {
-    if (url.endsWith('/api/internal/runtime-config')) revoked = JSON.parse(init.body);
-    return { ok: false };
-  };
-  const unavailable = await broken.syncEngineConfiguration();
-  assert.deepEqual(revoked, { settings: null });
-  assert.equal(unavailable.indexStorage.status, 'pending');
-  console.log('vector-storage-root-test PASS');
-}).catch(error => { console.error(error); process.exitCode = 1; });
+'use strict';
+const assert = require('node:assert/strict');
+const path = require('node:path');
+const { StorageLayout } = require('../lib/storage-layout');
+const { ModuleBridge } = require('../lib/module-bridge');
+const { KnowledgeToolRuntime } = require('../lib/knowledge-tool-runtime');
+const root = path.resolve('D:/knowledge storage 中文');
+const layout = new StorageLayout({ dataDir: path.resolve('D:/metadata') });
+assert.equal(layout.getVectorRootPath({ knowledge: { rootPath: root } }), path.join(root, '.indexes'));
+assert.equal(layout.getVectorRootPath({ knowledge: { rootPath: '' } }), path.join(layout.getDataDir(), 'vectorhub'));
+const settingsStore = { read: () => ({ knowledge: { rootPath: root }, brain: { id: 'brain-default', domains: [] } }) };
+let knowledgeRoot = root;
+const tools = new KnowledgeToolRuntime({
+  layout,
+  settingsStore: { read: () => ({ knowledge: { rootPath: knowledgeRoot } }) },
+  registryStore: { listIds: () => ['project-storage'] },
+  projectStore: {
+    readConfig: () => ({ displayName: 'Storage', repoPath: path.join(root, 'repo'), knowledgePath: path.join(root, 'project') }),
+    readState: () => ({ index: { generation: 3 } }),
+  },
+});
+assert.equal(tools.resolveProject({ projectId: 'project-storage' }).indexPath, path.join(root, '.indexes'), 'MCP/CLI resolution must report the vector-hub location, not the retired shell database');
+knowledgeRoot = path.join(root, 'changed root');
+assert.equal(tools.resolveProject({ projectId: 'project-storage' }).indexPath, path.join(knowledgeRoot, '.indexes'), 'a running MCP process must reread the selected knowledge root');
+knowledgeRoot = '';
+assert.equal(tools.resolveProject({ projectId: 'project-storage' }).indexPath, path.join(layout.getDataDir(), 'vectorhub'));
+const bridge = new ModuleBridge({ settingsStore, dataDir: layout.getDataDir() });
+// The supervisor refuses to spawn the vendored vector-hub on Node < 22
+// (module-bridge: "vector-hub declares engines >= 22"), so its supervised
+// spec — and these env assertions — only exist on qualifying runtimes.
+const vectorHubSpec = bridge._supervisedSpecs().find(spec => spec.name === 'vector-hub');
+if (parseInt(process.versions.node, 10) >= 22) {
+  assert.equal(vectorHubSpec.env.VECTOR_HUB_ROOT, path.join(root, '.indexes'));
+  assert.equal(vectorHubSpec.env.VECTOR_HUB_CONFIG, path.join(layout.getDataDir(), 'vectorhub', 'config.json'));
+} else {
+  assert.equal(vectorHubSpec, undefined, 'vector-hub must not be supervised on Node < 22');
+}
+const calls = [];
+bridge._fetch = async (url, init) => { const body = JSON.parse(init.body); calls.push({ url, body }); return { ok: true, json: async () => url.includes('/api/internal/runtime-config') ? { ok: true, rootPath: path.join(root, '.indexes') } : {} }; };
+bridge.syncEngineConfiguration().then(async status => {
+  assert.equal(calls.find(call => call.url.includes('/api/internal/runtime-config')).body.storageRoot, path.join(root, '.indexes'));
+  assert.equal(status.indexStorage.status, 'ready');
+  let currentRoot = root, release, started;
+  const entered = new Promise(resolve => { started = resolve; });
+  const held = new Promise(resolve => { release = resolve; });
+  const queued = new ModuleBridge({ dataDir: layout.getDataDir(), settingsStore: { read: () => ({ knowledge: { rootPath: currentRoot }, brain: { id: 'brain-default', domains: [] } }) } });
+  const applied = [];
+  queued._fetch = async (url, init) => {
+    const body = JSON.parse(init.body);
+    if (url.endsWith('/api/internal/runtime-config')) {
+      applied.push(body.storageRoot);
+      if (applied.length === 1) { started(); await held; }
+      return { ok: true, json: async () => ({ rootPath: body.storageRoot }) };
+    }
+    return { ok: true, json: async () => null };
+  };
+  const first = queued.syncEngineConfiguration(); await entered;
+  currentRoot = path.join(root, 'new root');
+  const second = queued.syncEngineConfiguration(); release();
+  await first;
+  const latest = await second;
+  assert.deepEqual(applied, [path.join(root, '.indexes'), path.join(currentRoot, '.indexes')]);
+  assert.equal(latest.indexStorage.actualPath, path.join(currentRoot, '.indexes'));
+  assert.equal(latest.indexStorage.status, 'ready');
+  const broken = new ModuleBridge({ dataDir: layout.getDataDir(), settingsStore: { read: () => { throw new Error('corrupt settings'); } } });
+  let revoked;
+  broken._fetch = async (url, init) => {
+    if (url.endsWith('/api/internal/runtime-config')) revoked = JSON.parse(init.body);
+    return { ok: false };
+  };
+  const unavailable = await broken.syncEngineConfiguration();
+  assert.deepEqual(revoked, { settings: null });
+  assert.equal(unavailable.indexStorage.status, 'pending');
+  console.log('vector-storage-root-test PASS');
+}).catch(error => { console.error(error); process.exitCode = 1; });