@sanqianx/project-knowledge 5.0.23 → 5.0.25

package/_site/lib/module-port-resolver.js

@@ -1,57 +1,57 @@
-'use strict';
-
-// Dynamic module URL resolution.
-//
-// Managed modules used to bind fixed default ports (terminal 5760,
-// vector-hub 8787, event-bridge 8790, engine 5790).  When a foreign process
-// occupied one of those ports the module crash-looped and the feature stayed
-// degraded.  This resolver picks the final URL BEFORE any module is spawned:
-//
-//   explicit env/option URL -> external service, untouched (legacy behavior)
-//   healthy identity match  -> reused (standalone module keeps running)
-//   otherwise               -> first free port from preferred +0..+19
-//   all busy                -> NO_FREE_MODULE_PORT (loud, never silent)
-
-function invalidUrl(value) {
-  return Object.assign(new Error(`Invalid module URL: ${value}`), { code: 'INVALID_MODULE_URL' });
-}
-
-function parsePreferredUrl(value) {
-  let parsed;
-  try { parsed = new URL(String(value)); } catch { throw invalidUrl(value); }
-  const port = Number(parsed.port);
-  if (!Number.isInteger(port) || port < 1 || port > 65535) throw invalidUrl(value);
-  return { parsed, port };
-}
-
-function rebuildUrl(parsed, port) {
-  const host = parsed.hostname.includes(':') ? `[${parsed.hostname}]` : parsed.hostname;
-  return `${parsed.protocol}//${host}:${port}`;
-}
-
-/**
- * @param {object} options
- * @param {string} options.kind module kind, used in errors/logs only
- * @param {string} options.preferredUrl default URL with an explicit port
- * @param {boolean} options.explicit true when the URL was injected explicitly
- * @param {(port: number) => Promise<boolean>} options.portFree TCP bind probe
- * @param {(url: string) => Promise<'module'|'foreign'|'unreachable'>} options.probe
- * @param {number} [options.scanRange] candidate count starting at the preferred port
- * @returns {Promise<{url: string, source: 'external'|'reused'|'dynamic', port: number, offset: number}>}
- */
-async function resolveModuleUrl({ kind, preferredUrl, explicit, portFree, probe, scanRange = 20 }) {
-  const { parsed, port } = parsePreferredUrl(preferredUrl);
-  if (explicit) return { url: preferredUrl, source: 'external', port, offset: 0 };
-  if (await probe(preferredUrl) === 'module') return { url: preferredUrl, source: 'reused', port, offset: 0 };
-  const range = Math.max(1, Number.isInteger(scanRange) ? scanRange : 20);
-  for (let offset = 0; offset < range && port + offset <= 65535; offset++) {
-    const candidate = port + offset;
-    if (await portFree(candidate)) {
-      return { url: rebuildUrl(parsed, candidate), source: 'dynamic', port: candidate, offset };
-    }
-  }
-  const last = Math.min(port + range - 1, 65535);
-  throw Object.assign(new Error(`No free port found for ${kind} in ${port}-${last}.`), { code: 'NO_FREE_MODULE_PORT' });
-}
-
-module.exports = { resolveModuleUrl };
+'use strict';
+
+// Dynamic module URL resolution.
+//
+// Managed modules used to bind fixed default ports (terminal 5760,
+// vector-hub 8787, event-bridge 8790, engine 5790).  When a foreign process
+// occupied one of those ports the module crash-looped and the feature stayed
+// degraded.  This resolver picks the final URL BEFORE any module is spawned:
+//
+//   explicit env/option URL -> external service, untouched (legacy behavior)
+//   healthy identity match  -> reused (standalone module keeps running)
+//   otherwise               -> first free port from preferred +0..+19
+//   all busy                -> NO_FREE_MODULE_PORT (loud, never silent)
+
+function invalidUrl(value) {
+  return Object.assign(new Error(`Invalid module URL: ${value}`), { code: 'INVALID_MODULE_URL' });
+}
+
+function parsePreferredUrl(value) {
+  let parsed;
+  try { parsed = new URL(String(value)); } catch { throw invalidUrl(value); }
+  const port = Number(parsed.port);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw invalidUrl(value);
+  return { parsed, port };
+}
+
+function rebuildUrl(parsed, port) {
+  const host = parsed.hostname.includes(':') ? `[${parsed.hostname}]` : parsed.hostname;
+  return `${parsed.protocol}//${host}:${port}`;
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.kind module kind, used in errors/logs only
+ * @param {string} options.preferredUrl default URL with an explicit port
+ * @param {boolean} options.explicit true when the URL was injected explicitly
+ * @param {(port: number) => Promise<boolean>} options.portFree TCP bind probe
+ * @param {(url: string) => Promise<'module'|'foreign'|'unreachable'>} options.probe
+ * @param {number} [options.scanRange] candidate count starting at the preferred port
+ * @returns {Promise<{url: string, source: 'external'|'reused'|'dynamic', port: number, offset: number}>}
+ */
+async function resolveModuleUrl({ kind, preferredUrl, explicit, portFree, probe, scanRange = 20 }) {
+  const { parsed, port } = parsePreferredUrl(preferredUrl);
+  if (explicit) return { url: preferredUrl, source: 'external', port, offset: 0 };
+  if (await probe(preferredUrl) === 'module') return { url: preferredUrl, source: 'reused', port, offset: 0 };
+  const range = Math.max(1, Number.isInteger(scanRange) ? scanRange : 20);
+  for (let offset = 0; offset < range && port + offset <= 65535; offset++) {
+    const candidate = port + offset;
+    if (await portFree(candidate)) {
+      return { url: rebuildUrl(parsed, candidate), source: 'dynamic', port: candidate, offset };
+    }
+  }
+  const last = Math.min(port + range - 1, 65535);
+  throw Object.assign(new Error(`No free port found for ${kind} in ${port}-${last}.`), { code: 'NO_FREE_MODULE_PORT' });
+}
+
+module.exports = { resolveModuleUrl };

package/_site/lib/post-commit-automation.js

@@ -1,141 +1,141 @@
-const fs = require('fs');
-const path = require('path');
-const { SCHEMAS, DomainError, validateProjectId } = require('./contracts');
-const { StorageLayout } = require('./storage-layout');
-const { ProjectRegistryStore } = require('./project-registry-store');
-const { ProjectStore } = require('./project-store');
-const { runGit } = require('./project-lifecycle-service');
-const { CommitReconciler, reconcileProjectCommits } = require('./commit-reconciler');
-const { validateSha } = require('./scanner');
-const { renderCommitPrompt } = require('./commit-prompt');
-
-function stores(deps = {}) {
-  const layout = deps.layout || new StorageLayout(deps);
-  return {
-    layout,
-    registryStore: deps.registryStore || new ProjectRegistryStore({ layout }),
-    projectStore: deps.projectStore || new ProjectStore({ layout }),
-  };
-}
-
-async function handlePostCommitEvent(event = {}, deps = {}) {
-  if (event.schema !== SCHEMAS.hookEvent) throw new DomainError('SCHEMA_UNSUPPORTED', 'Hook event must use hook-event/v2.', { status: 409 });
-  const projectId = validateProjectId(event.projectId);
-  const commitSha = validateSha(event.head, 'Hook event head');
-  if (!event.repoRoot) throw new DomainError('INVALID_ARGUMENT', 'Hook event repoRoot is required.');
-  const resolved = stores(deps);
-  if (!resolved.registryStore.readDisplaySnapshot(projectId)) throw new DomainError('PROJECT_NOT_FOUND', 'Hook projectId is not registered.', { status: 404 });
-  const config = resolved.projectStore.readConfig(projectId);
-  const runtimeRoot = path.resolve(runGit(path.resolve(event.repoRoot), ['rev-parse', '--show-toplevel']).stdout);
-  const commonDir = path.resolve(runtimeRoot, runGit(runtimeRoot, ['rev-parse', '--git-common-dir']).stdout);
-  if (config.repoIdentity && config.repoIdentity.commonDir
-    && !resolved.layout.pathsEqual(config.repoIdentity.commonDir, commonDir)) {
-    if (fs.existsSync(config.repoPath)) {
-      throw new DomainError('PROJECT_NOT_FOUND', 'Hook Git identity does not match projectId.', { status: 404 });
-    }
-    const state = resolved.projectStore.readState(projectId);
-    const baseline = state.lastAnalyzedCommit || state.trackingStartCommit;
-    if (baseline) {
-      const reachable = runGit(runtimeRoot, ['merge-base', '--is-ancestor', baseline, commitSha], { allowFailure: true });
-      if (!reachable.ok) throw new DomainError('PROJECT_NOT_FOUND', 'Moved Hook repository does not contain the project baseline.', { status: 404 });
-    }
-  }
-  if (!resolved.layout.pathsEqual(config.repoPath, runtimeRoot)) {
-    // Only the versioned Hook path reaches this update, after projectId and Git identity checks above.
-    await resolved.projectStore.updateConfig(projectId, { repoPath: runtimeRoot }, { allowRepoPath: true });
-  }
-  if (event.boundary && event.boundary.status === 'captured' && event.boundary.boundary) {
-    const boundary = event.boundary.boundary;
-    if (boundary.projectId !== projectId || boundary.commitSha !== commitSha) {
-      throw new DomainError('INVALID_ARGUMENT', 'Hook boundary identity does not match the Hook event.');
-    }
-    const commitExists = runGit(runtimeRoot, ['cat-file', '-e', `${boundary.commitSha}^{commit}`], { allowFailure: true });
-    if (!commitExists.ok) throw new DomainError('INVALID_ARGUMENT', 'Hook boundary commit does not exist in the repository.');
-    // Ordering (T13): the boundary was appended before the Hook notified us;
-    // drain the journal THROUGH the boundary sequence before any snapshot is
-    // bound, so every same-workspace event <= boundaryEndCursor is already in
-    // the ConversationStore (or deterministically handled) at freeze time.
-    if (deps.bridgeConsumerService && typeof deps.bridgeConsumerService.drainThrough === 'function') {
-      await deps.bridgeConsumerService.drainThrough(Number(boundary.journalSequence), 'commit-boundary');
-    }
-    if (deps.conversationStore && typeof deps.conversationStore.writeBoundary === 'function') {
-      deps.conversationStore.writeBoundary(projectId, boundary);
-    }
-  } else if (event.boundary && event.boundary.status === 'unavailable' && deps.logger && typeof deps.logger.warn === 'function') {
-    await deps.logger.warn('conversation.boundary_gap', 'Conversation boundary capture gap was reported by the Git Hook.', {
-      projectId,
-      operationId: deps.operationId || event.operationId || '',
-      commitSha: event.head || '',
-      phase: 'boundary',
-      context: {
-        gapId: event.boundary.gap && event.boundary.gap.gapId || '',
-        reason: event.boundary.gap && event.boundary.gap.reason || 'unavailable',
-      },
-    });
-  }
-  const reconciler = deps.reconciler instanceof CommitReconciler ? deps.reconciler : new CommitReconciler({ ...deps, ...resolved });
-  return reconciler.processCommitEvent({ projectId, commitSha, branch: event.branch || '', operationId: deps.operationId || event.operationId || '' });
-}
-
-function cleanupOrphanedRuns(_projects, deps = {}) {
-  if (!deps.projectStore && !deps.registryStore && !deps.layout) {
-    return { activeClaims: 0, recoveredFromFrozenClaims: 0, legacyStoreSkipped: true };
-  }
-  const resolved = stores(deps);
-  let activeClaims = 0;
-  for (const projectId of resolved.registryStore.listIds()) {
-    if (resolved.projectStore.readState(projectId).analysis.activeClaim) activeClaims += 1;
-  }
-  return { activeClaims, recoveredFromFrozenClaims: activeClaims };
-}
-
-async function recoverOrphanedClaims(deps = {}) {
-  const resolved = stores(deps);
-  const recovered = [];
-  for (const projectId of resolved.registryStore.listIds()) {
-    const state = resolved.projectStore.readState(projectId);
-    const orphaned = state.analysis.activeClaim;
-    if (!orphaned) continue;
-    if (orphaned.phase === 'failed' && orphaned.error && orphaned.error.code === 'ORPHANED_CLAIM') continue;
-    const recoveredAt = typeof deps.now === 'function' ? deps.now() : new Date().toISOString();
-    const error = {
-      code: 'ORPHANED_CLAIM',
-      message: 'Commit analysis was interrupted by a previous process exit.',
-      phase: String(orphaned.phase || state.analysis.status || 'unknown'),
-      retryable: false,
-      ts: recoveredAt,
-    };
-    await resolved.projectStore.updateState(projectId, draft => {
-      if (!draft.analysis.activeClaim) return;
-      draft.analysis.activeClaim.phase = 'failed';
-      draft.analysis.activeClaim.error = error;
-      draft.analysis.status = 'failed';
-      draft.analysis.lastError = error;
-    }, { expectedRevision: state.revision });
-    recovered.push({
-      projectId,
-      commitSha: String(orphaned.commitSha || ''),
-      runId: String(orphaned.runId || ''),
-      previousPhase: error.phase,
-    });
-    if (deps.logger && typeof deps.logger.warn === 'function') {
-      await deps.logger.warn('reconcile.orphaned_claim_recovered', 'An interrupted commit claim was made terminal without retrying analysis.', {
-        projectId,
-        commitSha: String(orphaned.commitSha || ''),
-        runId: String(orphaned.runId || ''),
-        phase: 'recovery',
-        context: { previousPhase: error.phase },
-      });
-    }
-  }
-  return recovered;
-}
-
-module.exports = {
-  CommitReconciler,
-  cleanupOrphanedRuns,
-  handlePostCommitEvent,
-  recoverOrphanedClaims,
-  reconcileProjectCommits,
-  renderCommitPrompt,
-};
+const fs = require('fs');
+const path = require('path');
+const { SCHEMAS, DomainError, validateProjectId } = require('./contracts');
+const { StorageLayout } = require('./storage-layout');
+const { ProjectRegistryStore } = require('./project-registry-store');
+const { ProjectStore } = require('./project-store');
+const { runGit } = require('./project-lifecycle-service');
+const { CommitReconciler, reconcileProjectCommits } = require('./commit-reconciler');
+const { validateSha } = require('./scanner');
+const { renderCommitPrompt } = require('./commit-prompt');
+
+function stores(deps = {}) {
+  const layout = deps.layout || new StorageLayout(deps);
+  return {
+    layout,
+    registryStore: deps.registryStore || new ProjectRegistryStore({ layout }),
+    projectStore: deps.projectStore || new ProjectStore({ layout }),
+  };
+}
+
+async function handlePostCommitEvent(event = {}, deps = {}) {
+  if (event.schema !== SCHEMAS.hookEvent) throw new DomainError('SCHEMA_UNSUPPORTED', 'Hook event must use hook-event/v2.', { status: 409 });
+  const projectId = validateProjectId(event.projectId);
+  const commitSha = validateSha(event.head, 'Hook event head');
+  if (!event.repoRoot) throw new DomainError('INVALID_ARGUMENT', 'Hook event repoRoot is required.');
+  const resolved = stores(deps);
+  if (!resolved.registryStore.readDisplaySnapshot(projectId)) throw new DomainError('PROJECT_NOT_FOUND', 'Hook projectId is not registered.', { status: 404 });
+  const config = resolved.projectStore.readConfig(projectId);
+  const runtimeRoot = path.resolve(runGit(path.resolve(event.repoRoot), ['rev-parse', '--show-toplevel']).stdout);
+  const commonDir = path.resolve(runtimeRoot, runGit(runtimeRoot, ['rev-parse', '--git-common-dir']).stdout);
+  if (config.repoIdentity && config.repoIdentity.commonDir
+    && !resolved.layout.pathsEqual(config.repoIdentity.commonDir, commonDir)) {
+    if (fs.existsSync(config.repoPath)) {
+      throw new DomainError('PROJECT_NOT_FOUND', 'Hook Git identity does not match projectId.', { status: 404 });
+    }
+    const state = resolved.projectStore.readState(projectId);
+    const baseline = state.lastAnalyzedCommit || state.trackingStartCommit;
+    if (baseline) {
+      const reachable = runGit(runtimeRoot, ['merge-base', '--is-ancestor', baseline, commitSha], { allowFailure: true });
+      if (!reachable.ok) throw new DomainError('PROJECT_NOT_FOUND', 'Moved Hook repository does not contain the project baseline.', { status: 404 });
+    }
+  }
+  if (!resolved.layout.pathsEqual(config.repoPath, runtimeRoot)) {
+    // Only the versioned Hook path reaches this update, after projectId and Git identity checks above.
+    await resolved.projectStore.updateConfig(projectId, { repoPath: runtimeRoot }, { allowRepoPath: true });
+  }
+  if (event.boundary && event.boundary.status === 'captured' && event.boundary.boundary) {
+    const boundary = event.boundary.boundary;
+    if (boundary.projectId !== projectId || boundary.commitSha !== commitSha) {
+      throw new DomainError('INVALID_ARGUMENT', 'Hook boundary identity does not match the Hook event.');
+    }
+    const commitExists = runGit(runtimeRoot, ['cat-file', '-e', `${boundary.commitSha}^{commit}`], { allowFailure: true });
+    if (!commitExists.ok) throw new DomainError('INVALID_ARGUMENT', 'Hook boundary commit does not exist in the repository.');
+    // Ordering (T13): the boundary was appended before the Hook notified us;
+    // drain the journal THROUGH the boundary sequence before any snapshot is
+    // bound, so every same-workspace event <= boundaryEndCursor is already in
+    // the ConversationStore (or deterministically handled) at freeze time.
+    if (deps.bridgeConsumerService && typeof deps.bridgeConsumerService.drainThrough === 'function') {
+      await deps.bridgeConsumerService.drainThrough(Number(boundary.journalSequence), 'commit-boundary');
+    }
+    if (deps.conversationStore && typeof deps.conversationStore.writeBoundary === 'function') {
+      deps.conversationStore.writeBoundary(projectId, boundary);
+    }
+  } else if (event.boundary && event.boundary.status === 'unavailable' && deps.logger && typeof deps.logger.warn === 'function') {
+    await deps.logger.warn('conversation.boundary_gap', 'Conversation boundary capture gap was reported by the Git Hook.', {
+      projectId,
+      operationId: deps.operationId || event.operationId || '',
+      commitSha: event.head || '',
+      phase: 'boundary',
+      context: {
+        gapId: event.boundary.gap && event.boundary.gap.gapId || '',
+        reason: event.boundary.gap && event.boundary.gap.reason || 'unavailable',
+      },
+    });
+  }
+  const reconciler = deps.reconciler instanceof CommitReconciler ? deps.reconciler : new CommitReconciler({ ...deps, ...resolved });
+  return reconciler.processCommitEvent({ projectId, commitSha, branch: event.branch || '', operationId: deps.operationId || event.operationId || '' });
+}
+
+function cleanupOrphanedRuns(_projects, deps = {}) {
+  if (!deps.projectStore && !deps.registryStore && !deps.layout) {
+    return { activeClaims: 0, recoveredFromFrozenClaims: 0, legacyStoreSkipped: true };
+  }
+  const resolved = stores(deps);
+  let activeClaims = 0;
+  for (const projectId of resolved.registryStore.listIds()) {
+    if (resolved.projectStore.readState(projectId).analysis.activeClaim) activeClaims += 1;
+  }
+  return { activeClaims, recoveredFromFrozenClaims: activeClaims };
+}
+
+async function recoverOrphanedClaims(deps = {}) {
+  const resolved = stores(deps);
+  const recovered = [];
+  for (const projectId of resolved.registryStore.listIds()) {
+    const state = resolved.projectStore.readState(projectId);
+    const orphaned = state.analysis.activeClaim;
+    if (!orphaned) continue;
+    if (orphaned.phase === 'failed' && orphaned.error && orphaned.error.code === 'ORPHANED_CLAIM') continue;
+    const recoveredAt = typeof deps.now === 'function' ? deps.now() : new Date().toISOString();
+    const error = {
+      code: 'ORPHANED_CLAIM',
+      message: 'Commit analysis was interrupted by a previous process exit.',
+      phase: String(orphaned.phase || state.analysis.status || 'unknown'),
+      retryable: false,
+      ts: recoveredAt,
+    };
+    await resolved.projectStore.updateState(projectId, draft => {
+      if (!draft.analysis.activeClaim) return;
+      draft.analysis.activeClaim.phase = 'failed';
+      draft.analysis.activeClaim.error = error;
+      draft.analysis.status = 'failed';
+      draft.analysis.lastError = error;
+    }, { expectedRevision: state.revision });
+    recovered.push({
+      projectId,
+      commitSha: String(orphaned.commitSha || ''),
+      runId: String(orphaned.runId || ''),
+      previousPhase: error.phase,
+    });
+    if (deps.logger && typeof deps.logger.warn === 'function') {
+      await deps.logger.warn('reconcile.orphaned_claim_recovered', 'An interrupted commit claim was made terminal without retrying analysis.', {
+        projectId,
+        commitSha: String(orphaned.commitSha || ''),
+        runId: String(orphaned.runId || ''),
+        phase: 'recovery',
+        context: { previousPhase: error.phase },
+      });
+    }
+  }
+  return recovered;
+}
+
+module.exports = {
+  CommitReconciler,
+  cleanupOrphanedRuns,
+  handlePostCommitEvent,
+  recoverOrphanedClaims,
+  reconcileProjectCommits,
+  renderCommitPrompt,
+};

package/_site/lib/product-data.js

@@ -1,35 +1,35 @@
-const fs = require('fs');
-const path = require('path');
-const AtomicFile = require('./atomic-file');
-const { DomainError } = require('./contracts');
-
-const DATA_SCHEMA = 'project-knowledge/fresh-product-data/v1';
-
-function hasData(file) {
-  return fs.existsSync(file) && (!fs.statSync(file).isDirectory() || fs.readdirSync(file).length > 0);
-}
-
-function initializeProductData(dataPath) {
-  const marker = path.join(dataPath, 'product-data.json');
-  if (fs.existsSync(marker)) {
-    const value = AtomicFile.readJsonStrict(marker);
-    if (value.schema !== DATA_SCHEMA) throw new DomainError('SCHEMA_UNSUPPORTED', '数据目录格式不受支持，请使用新的空目录重新导入项目。', { status: 409 });
-    return;
-  }
-  // Old registries and unfinished claims must never become fresh product work.
-  const oldData = ['settings.json', 'projects.json', 'projects', 'knowledge-engine', 'workbench', 'vectorhub', 'events', 'knowledge-store.json', 'ai-profiles.json', 'embedding-config.json']
-    .filter(name => hasData(path.join(dataPath, name)));
-  const runtimePath = path.join(dataPath, 'runtime');
-  if (fs.existsSync(runtimePath)) {
-    if (!fs.statSync(runtimePath).isDirectory()) oldData.push('runtime');
-    else for (const name of fs.readdirSync(runtimePath)) {
-      // Unregistered legacy chat records cannot be resumed by a fresh registry.
-      // They are neither knowledge nor pending maintenance, and stay untouched.
-      if (name !== 'claude-sessions' && hasData(path.join(runtimePath, name))) oldData.push(`runtime/${name}`);
-    }
-  }
-  if (oldData.length) throw new DomainError('SCHEMA_UNSUPPORTED', `数据目录 ${dataPath} 包含旧版业务数据（${oldData.join('、')}）。新版不会迁移或删除它们；请将 KB_DATA_DIR 指向新的空目录，然后重新导入项目。`, { status: 409, details: { dataPath, entries: oldData } });
-  AtomicFile.writeJsonAtomic(marker, { schema: DATA_SCHEMA, createdAt: new Date().toISOString() });
-}
-
-module.exports = { initializeProductData, DATA_SCHEMA };
+const fs = require('fs');
+const path = require('path');
+const AtomicFile = require('./atomic-file');
+const { DomainError } = require('./contracts');
+
+const DATA_SCHEMA = 'project-knowledge/fresh-product-data/v1';
+
+function hasData(file) {
+  return fs.existsSync(file) && (!fs.statSync(file).isDirectory() || fs.readdirSync(file).length > 0);
+}
+
+function initializeProductData(dataPath) {
+  const marker = path.join(dataPath, 'product-data.json');
+  if (fs.existsSync(marker)) {
+    const value = AtomicFile.readJsonStrict(marker);
+    if (value.schema !== DATA_SCHEMA) throw new DomainError('SCHEMA_UNSUPPORTED', '数据目录格式不受支持，请使用新的空目录重新导入项目。', { status: 409 });
+    return;
+  }
+  // Old registries and unfinished claims must never become fresh product work.
+  const oldData = ['settings.json', 'projects.json', 'projects', 'knowledge-engine', 'workbench', 'vectorhub', 'events', 'knowledge-store.json', 'ai-profiles.json', 'embedding-config.json']
+    .filter(name => hasData(path.join(dataPath, name)));
+  const runtimePath = path.join(dataPath, 'runtime');
+  if (fs.existsSync(runtimePath)) {
+    if (!fs.statSync(runtimePath).isDirectory()) oldData.push('runtime');
+    else for (const name of fs.readdirSync(runtimePath)) {
+      // Unregistered legacy chat records cannot be resumed by a fresh registry.
+      // They are neither knowledge nor pending maintenance, and stay untouched.
+      if (name !== 'claude-sessions' && hasData(path.join(runtimePath, name))) oldData.push(`runtime/${name}`);
+    }
+  }
+  if (oldData.length) throw new DomainError('SCHEMA_UNSUPPORTED', `数据目录 ${dataPath} 包含旧版业务数据（${oldData.join('、')}）。新版不会迁移或删除它们；请将 KB_DATA_DIR 指向新的空目录，然后重新导入项目。`, { status: 409, details: { dataPath, entries: oldData } });
+  AtomicFile.writeJsonAtomic(marker, { schema: DATA_SCHEMA, createdAt: new Date().toISOString() });
+}
+
+module.exports = { initializeProductData, DATA_SCHEMA };