@sanqianx/project-knowledge 4.6.1

package/_site/lib/markdown-knowledge-indexer.js

@@ -0,0 +1,230 @@
+const fs = require('fs');
+const path = require('path');
+const { sha256 } = require('./knowledge-schema');
+
+const CHUNKER_VERSION = 1;
+const DEFAULT_MAX_CHARS = 1200;
+const DEFAULT_OVERLAP_CHARS = 120;
+const EXCLUDED_DIRS = new Set(['.git', '_ai', '_backup', 'node_modules']);
+const DERIVED_INDEX_FILENAME = '00-index.md';
+
+function normalizeRel(value) {
+  return String(value || '').replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function stripFrontmatter(markdown) {
+  return String(markdown || '').replace(/^---\s*\r?\n[\s\S]*?\r?\n---\s*\r?\n?/, '');
+}
+
+function parseListValue(value) {
+  const raw = String(value || '').trim();
+  const body = raw.startsWith('[') && raw.endsWith(']') ? raw.slice(1, -1) : raw;
+  return body.split(',').map(item => item.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean);
+}
+
+function parseKnowledgeMetadata(markdown) {
+  const match = /^---\s*\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/.exec(String(markdown || ''));
+  if (!match) return { tags: [], sourcePaths: [], routes: [], symbols: [], affectedModules: [] };
+  const values = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const field = /^([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(line);
+    if (field) values[field[1].toLowerCase()] = field[2];
+  }
+  return {
+    tags: parseListValue(values.tags),
+    sourcePaths: parseListValue(values.sourcepaths || values.source_paths),
+    routes: parseListValue(values.routes),
+    symbols: parseListValue(values.symbols),
+    affectedModules: parseListValue(values.affectedmodules || values.affected_modules),
+  };
+}
+
+function splitLongText(text, maxChars, overlapChars) {
+  const clean = String(text || '').trim();
+  if (!clean) return [];
+  if (clean.length <= maxChars) return [clean];
+  const parts = [];
+  let start = 0;
+  while (start < clean.length) {
+    let end = Math.min(start + maxChars, clean.length);
+    if (end < clean.length) {
+      const floor = start + Math.floor(maxChars * 0.6);
+      const boundary = Math.max(clean.lastIndexOf('\n\n', end), clean.lastIndexOf('。', end), clean.lastIndexOf('. ', end));
+      if (boundary >= floor) end = boundary + 1;
+    }
+    parts.push(clean.slice(start, end).trim());
+    if (end >= clean.length) break;
+    start = Math.max(start + 1, end - overlapChars);
+  }
+  return parts.filter(Boolean);
+}
+
+function chunkMarkdown(markdown, options = {}) {
+  const maxChars = Number(options.maxChars || DEFAULT_MAX_CHARS);
+  const overlapChars = Math.min(Number(options.overlapChars || DEFAULT_OVERLAP_CHARS), Math.floor(maxChars / 3));
+  const body = stripFrontmatter(markdown).replace(/\r\n/g, '\n');
+  const lines = body.split('\n');
+  const headings = [];
+  const sections = [];
+  let buffer = [];
+  let sectionHeadings = [];
+
+  const flush = () => {
+    const text = buffer.join('\n').trim();
+    if (text) sections.push({ headingPath: [...sectionHeadings], text });
+    buffer = [];
+  };
+
+  for (const line of lines) {
+    const match = /^(#{1,6})\s+(.+?)\s*$/.exec(line);
+    if (match) {
+      flush();
+      const level = match[1].length;
+      headings.length = level - 1;
+      headings[level - 1] = match[2].trim();
+      sectionHeadings = headings.filter(Boolean);
+      buffer.push(line);
+    } else {
+      buffer.push(line);
+    }
+  }
+  flush();
+
+  const chunks = [];
+  for (const section of sections) {
+    for (const text of splitLongText(section.text, maxChars, overlapChars)) {
+      chunks.push({
+        chunkOrder: chunks.length,
+        headingPath: section.headingPath,
+        chunkText: text,
+      });
+    }
+  }
+  return chunks;
+}
+
+function isDerivedIndex(filePath) {
+  return path.basename(String(filePath || '')).toLowerCase() === DERIVED_INDEX_FILENAME;
+}
+
+function listMarkdownFiles(root, options = {}) {
+  const includeDerived = options.includeDerived === true;
+  const files = [];
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith('.') || EXCLUDED_DIRS.has(entry.name)) continue;
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) walk(abs);
+      else if (entry.isFile() && /\.md$/i.test(entry.name) && (includeDerived || !isDerivedIndex(entry.name))) files.push(abs);
+    }
+  };
+  if (fs.existsSync(root)) walk(path.resolve(root));
+  return files.sort();
+}
+
+function inferEntryType(relativePath) {
+  const rel = normalizeRel(relativePath).toLowerCase();
+  if (rel === 'goal.md') return 'goal';
+  if (rel === 'architecture.md') return 'architecture';
+  if (rel.startsWith('modules/')) return 'module';
+  if (rel.startsWith('changes/')) return 'change';
+  return 'document';
+}
+
+function inferTitle(markdown, relativePath) {
+  const heading = /^#\s+(.+)$/m.exec(stripFrontmatter(markdown));
+  return heading ? heading[1].trim() : path.basename(relativePath, path.extname(relativePath));
+}
+
+class MarkdownKnowledgeIndexer {
+  constructor(options = {}) {
+    if (!options.database) throw new Error('database is required');
+    if (!options.embedder) throw new Error('embedder is required');
+    this.database = options.database;
+    this.embedder = options.embedder;
+    this.maxChars = options.maxChars || DEFAULT_MAX_CHARS;
+    this.overlapChars = options.overlapChars || DEFAULT_OVERLAP_CHARS;
+  }
+
+  async indexFile(input) {
+    const filePath = path.resolve(input.filePath);
+    const relativePath = normalizeRel(input.relativePath || path.basename(filePath));
+    const markdown = fs.readFileSync(filePath, 'utf8');
+    const documentHash = sha256(`chunker:${CHUNKER_VERSION}\n${markdown}`);
+    const existing = await this.database.rowsForEntry(input.spaceId, relativePath);
+    if (existing.length && existing.every(row => row.document_hash === documentHash)) {
+      return { ok: true, action: 'unchanged', entryId: relativePath, chunks: existing.length, documentHash };
+    }
+    const title = inferTitle(markdown, relativePath);
+    const metadata = parseKnowledgeMetadata(markdown);
+    const rawChunks = chunkMarkdown(markdown, { maxChars: this.maxChars, overlapChars: this.overlapChars });
+    const chunks = [];
+    for (const chunk of rawChunks) {
+      const embeddingText = [title, chunk.headingPath.join(' > '), chunk.chunkText].filter(Boolean).join('\n');
+      chunks.push({
+        ...chunk,
+        title,
+        entryType: inferEntryType(relativePath),
+        // Keyword search now indexes chunk_text directly. Keep only compact
+        // title/heading metadata in the legacy search_text column so new rows
+        // do not duplicate the entire document body.
+        searchText: [title, chunk.headingPath.join(' > ')].filter(Boolean).join('\n'),
+        vector: await this.embedder.embedPassage(embeddingText),
+        tags: [...new Set([...metadata.tags, ...metadata.affectedModules])],
+        sourcePaths: metadata.sourcePaths.length ? metadata.sourcePaths : input.sourcePaths || [],
+        routes: metadata.routes,
+        symbols: metadata.symbols,
+        sourceProjectId: input.sourceProjectId || '',
+        sourceCommit: input.sourceCommit || '',
+        documentHash,
+      });
+    }
+    const result = await this.database.replaceEntry(input.spaceId, relativePath, chunks);
+    return { ...result, entryId: relativePath, chunks: chunks.length, documentHash };
+  }
+
+  async indexDirectory(input) {
+    const root = path.resolve(input.kbPath);
+    const files = listMarkdownFiles(root);
+    const present = new Set();
+    const results = [];
+    for (const filePath of files) {
+      const relativePath = normalizeRel(path.relative(root, filePath));
+      present.add(relativePath);
+      results.push(await this.indexFile({ ...input, filePath, relativePath }));
+    }
+    const stale = (await this.database.entryIds(input.spaceId)).filter(entryId => !present.has(entryId));
+    let deletedChunks = 0;
+    for (const entryId of stale) deletedChunks += (await this.database.deleteEntry(input.spaceId, entryId)).deleted;
+    const changed = results.filter(item => item.action !== 'unchanged');
+    const operations = changed.length + stale.length;
+    const rows = changed.reduce((sum, item) => sum + Number(item.upserted || 0) + Number(item.deleted || 0), 0) + deletedChunks;
+    const mutationState = this.database.noteMutations({ operations, rows });
+    let maintenance = { ok: true, optimized: false, deferred: input.deferMaintenance === true, state: mutationState };
+    if (await this.database.count([input.spaceId])) {
+      await this.database.ensureSearchIndexes();
+      if (input.deferMaintenance !== true) maintenance = await this.database.maybeOptimize();
+    }
+    return {
+      ok: true,
+      spaceId: input.spaceId,
+      files: files.length,
+      indexed: changed.length,
+      unchanged: results.filter(item => item.action === 'unchanged').length,
+      deletedEntries: stale.length,
+      deletedChunks,
+      maintenance,
+      results,
+    };
+  }
+}
+
+module.exports = {
+  MarkdownKnowledgeIndexer,
+  CHUNKER_VERSION,
+  chunkMarkdown,
+  listMarkdownFiles,
+  isDerivedIndex,
+  inferEntryType,
+  parseKnowledgeMetadata,
+};

package/_site/lib/migration-service.js

@@ -0,0 +1,442 @@
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { SCHEMAS, SCHEMA_VERSIONS, DomainError } = require('./contracts');
+const AtomicFile = require('./atomic-file');
+const { StorageLayout } = require('./storage-layout');
+const { defaultSettings, validateSettings } = require('./settings-store');
+const { emptyRegistry, validateRegistry } = require('./project-registry-store');
+const { defaultProjectConfig, defaultProjectState, validateProjectConfig, validateProjectState } = require('./project-store');
+const { LEGACY_ASSETS, getLegacyAsset, assetPath } = require('./legacy-data-manifest');
+const { STATES, classifyDataState } = require('./data-state-classifier');
+
+function hashBuffer(buffer) { return crypto.createHash('sha256').update(buffer).digest('hex'); }
+function hashFile(filePath) { return hashBuffer(fs.readFileSync(filePath)); }
+
+function copyRecursive(source, target) {
+  const stat = fs.statSync(source);
+  if (stat.isDirectory()) {
+    fs.mkdirSync(target, { recursive: true });
+    for (const entry of fs.readdirSync(source)) copyRecursive(path.join(source, entry), path.join(target, entry));
+    return;
+  }
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.copyFileSync(source, target, fs.constants.COPYFILE_EXCL);
+}
+
+function removeOwnedPath(target) {
+  if (!fs.existsSync(target)) return;
+  fs.rmSync(target, { recursive: true, force: true });
+}
+
+function pruneEmptyParents(target, boundary) {
+  const root = path.resolve(boundary);
+  let current = path.dirname(path.resolve(target));
+  while (current !== root && current.startsWith(`${root}${path.sep}`)) {
+    if (!fs.existsSync(current) || fs.readdirSync(current).length > 0) break;
+    fs.rmdirSync(current);
+    current = path.dirname(current);
+  }
+}
+
+function deterministicProjectId(slug, config) {
+  const identity = String(config && (config.projectId || config.gitPath || config.localPath || config.repoPath) || slug);
+  const existing = String(config && config.projectId || '');
+  if (/^[A-Za-z0-9][A-Za-z0-9._-]{2,127}$/.test(existing)) return existing;
+  return `project-${crypto.createHash('sha256').update(`${slug}\0${identity}`).digest('hex').slice(0, 20)}`;
+}
+
+function safeReadJson(filePath, fallback = null) {
+  if (!fs.existsSync(filePath)) return fallback;
+  try {
+    // Legacy files written via PowerShell/tooling often carry a UTF-8 BOM;
+    // JSON.parse rejects it, and a BOM must never fail the whole migration.
+    const raw = fs.readFileSync(filePath, 'utf8');
+    return JSON.parse(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw);
+  }
+  catch (error) { throw new DomainError('DATA_CORRUPT', 'Legacy migration source JSON is corrupt.', { status: 500, cause: error, details: { category: path.basename(filePath) } }); }
+}
+
+function sourceSnapshot(paths) {
+  const entries = [];
+  for (const source of paths) {
+    if (!fs.existsSync(source)) continue;
+    const stat = fs.statSync(source);
+    entries.push({
+      path: source,
+      kind: stat.isDirectory() ? 'directory' : 'file',
+      size: stat.size,
+      mtimeMs: stat.mtimeMs,
+      hash: stat.isFile() ? hashFile(source) : '',
+    });
+  }
+  return entries;
+}
+
+function verifySourceSnapshot(entries) {
+  for (const entry of entries) {
+    if (!fs.existsSync(entry.path)) return false;
+    const stat = fs.statSync(entry.path);
+    if (entry.kind === 'file' && (stat.size !== entry.size || hashFile(entry.path) !== entry.hash)) return false;
+  }
+  return true;
+}
+
+function directoryDigest(root) {
+  const hash = crypto.createHash('sha256');
+  const walk = current => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const item = path.join(current, entry.name);
+      hash.update(`${entry.isDirectory() ? 'd' : 'f'}:${path.relative(root, item).replace(/\\/g, '/')}\0`);
+      if (entry.isDirectory()) walk(item); else if (entry.isFile()) hash.update(fs.readFileSync(item));
+    }
+  };
+  walk(root);
+  return hash.digest('hex');
+}
+
+class MigrationService {
+  constructor(options = {}) {
+    this.layout = options.layout || new StorageLayout(options);
+    this.atomic = options.atomic || AtomicFile;
+    this.legacyDataDir = path.resolve(options.legacyDataDir || this.layout.getDataDir());
+    this.indexValidator = options.indexValidator || (async indexPath => ({ ok: fs.existsSync(indexPath) }));
+    this.logger = options.logger || { info() {}, warn() {}, error() {} };
+  }
+
+  completion() {
+    const completionPath = this.layout.getMigrationCompletionPath();
+    if (!fs.existsSync(completionPath)) return null;
+    const marker = this.atomic.readJsonStrict(completionPath, { category: 'layout-migration-completion' });
+    return marker && ['layout-migration-completion/v1', 'layout-migration-completion/v2'].includes(marker.schema) && marker.migrationId === SCHEMA_VERSIONS.layoutMigration
+      ? marker
+      : null;
+  }
+
+  completionMarker({ runId = '', registry, settings, modelsMigrated = false } = {}) {
+    const profiles = settings && settings.ai && Array.isArray(settings.ai.profiles) ? settings.ai.profiles : [];
+    return {
+      schema: 'layout-migration-completion/v2',
+      migrationId: SCHEMA_VERSIONS.layoutMigration,
+      runId,
+      sourceRoot: this.legacyDataDir,
+      sourceManifestHash: hashBuffer(Buffer.from(JSON.stringify(LEGACY_ASSETS.map(asset => [asset.source, asset.target, asset.kind])))),
+      projectCount: registry.projectOrder.length,
+      aiProfileCount: profiles.length,
+      knowledgeRootConfigured: Boolean(settings.knowledge && settings.knowledge.rootPath),
+      embeddingConfigured: Boolean(settings.embedding && Object.keys(settings.embedding).length),
+      modelsMigrated,
+      completedAt: new Date().toISOString(),
+      verified: true,
+    };
+  }
+
+  validateCompletedState(marker) {
+    try {
+      const registry = this.atomic.readJsonStrict(this.layout.getProjectRegistryPath(), { category: 'project-registry' });
+      validateRegistry(registry);
+      const settings = this.atomic.readJsonStrict(this.layout.getSettingsPath(), { category: 'settings' });
+      validateSettings(settings);
+      for (const projectId of registry.projectOrder) {
+        validateProjectConfig(this.atomic.readJsonStrict(this.layout.getProjectConfigPath(projectId), { category: 'project-config' }), projectId);
+        validateProjectState(this.atomic.readJsonStrict(this.layout.getProjectStatePath(projectId), { category: 'project-state' }));
+      }
+      // marker.projectCount is a migration-time snapshot only. Imports and
+      // deletions legitimately change the live registry count afterwards;
+      // comparing them here rejected every restart after the first legal
+      // project removal (completion-project-count-mismatch false positive).
+      return { ok: true, registry, settings };
+    } catch (error) { return { ok: false, reason: 'completion-state-invalid', error }; }
+  }
+
+  discover() {
+    const paths = LEGACY_ASSETS.map(asset => assetPath(this.legacyDataDir, asset)).filter(file => fs.existsSync(file));
+    const knowledgeStore = safeReadJson(path.join(this.legacyDataDir, 'knowledge-store.json'), {});
+    const indexCandidates = [
+      path.join(this.legacyDataDir, 'knowledge.lancedb'),
+      knowledgeStore && knowledgeStore.rootPath ? path.join(path.resolve(knowledgeStore.rootPath), '.project-knowledge', 'knowledge.lancedb') : '',
+    ].filter(Boolean);
+    const indexPath = indexCandidates.find(candidate => fs.existsSync(candidate)) || '';
+    if (indexPath) paths.push(indexPath);
+    return {
+      legacyProjectsPath: path.join(this.legacyDataDir, 'projects.json'),
+      knowledgeStore,
+      indexPath,
+      modelsPath: assetPath(this.legacyDataDir, getLegacyAsset('models')),
+      sources: sourceSnapshot(paths),
+    };
+  }
+
+  mergeLegacySettings(discovery) {
+    const settings = defaultSettings();
+    const read = name => safeReadJson(path.join(this.legacyDataDir, name), null);
+    const knowledge = read('knowledge-store.json');
+    const ai = read('ai-profiles.json');
+    const embedding = read('embedding-config.json');
+    const logging = read('logging.json');
+    const prompts = read('claude-prompts.json');
+    const github = read('github-team.json');
+    const providers = read('team-git-providers.json');
+    if (knowledge && typeof knowledge.rootPath === 'string') settings.knowledge.rootPath = knowledge.rootPath;
+    if (ai && typeof ai === 'object') settings.ai = ai;
+    if (embedding && typeof embedding === 'object') settings.embedding = embedding;
+    if (logging && typeof logging === 'object') {
+      if (Array.isArray(logging.levels)) settings.logging.levels = logging.levels;
+      settings.legacyExtensions.logging = { ...logging };
+    }
+    if (prompts && typeof prompts === 'object') settings.promptOverrides = prompts;
+    if (github || providers) settings.integrations = { ...(settings.integrations || {}), ...(github ? { githubTeam: github } : {}), ...(providers ? { teamGitProviders: providers } : {}) };
+    settings.updatedAt = new Date().toISOString();
+    return validateSettings(settings);
+  }
+
+  buildProjectRecords(legacyProjects, settings) {
+    const registry = emptyRegistry();
+    const records = [];
+    for (const [slug, rawConfig] of Object.entries(legacyProjects || {})) {
+      const legacy = rawConfig && rawConfig.config && typeof rawConfig.config === 'object' ? rawConfig.config : (rawConfig || {});
+      const projectId = deterministicProjectId(slug, legacy);
+      const knowledgePath = legacy.knowledgePath || legacy.kbPath || (settings.knowledge.rootPath ? path.join(path.resolve(settings.knowledge.rootPath), slug) : path.join(this.legacyDataDir, 'projects', slug));
+      const config = defaultProjectConfig(projectId, {
+        displayName: legacy.displayName || slug,
+        storageName: legacy.storageName || `${slug}-${projectId.slice(-6)}`,
+        repoPath: legacy.repoPath || legacy.gitPath || legacy.localPath || this.legacyDataDir,
+        knowledgePath,
+        enabled: legacy.enabled !== false,
+        createdAt: legacy.createdAt || new Date(0).toISOString(),
+        teamBinding: legacy.teamBinding || (legacy.teamKbId ? { teamKbId: legacy.teamKbId } : null),
+        aiProfileId: legacy.aiProfileId || null,
+        knowledgeLanguage: legacy.knowledgeLanguage || 'zh-CN',
+        relatedProjectIds: legacy.relatedProjectIds || [],
+        repoIdentity: legacy.repoIdentity || null,
+        legacyExtensions: { slug, sourceSchema: legacy.schema || '' },
+      });
+      const hasTracking = Boolean(legacy.trackingStartCommit || legacy.lastAnalyzedCommit);
+      const state = defaultProjectState({
+        trackingStartCommit: legacy.trackingStartCommit || null,
+        lastAnalyzedCommit: legacy.lastAnalyzedCommit || null,
+        trackingMode: hasTracking ? 'normal' : (legacy.repoStatus === 'empty-repo' ? 'empty-repo' : 'normal'),
+        hook: { managedVersion: 0, migrationVersion: 0, lastVerifiedAt: '' },
+      });
+      validateProjectConfig(config, projectId);
+      validateProjectState(state);
+      registry.projectOrder.push(projectId);
+      registry.projects[projectId] = { createdAt: config.createdAt, displayNameSnapshot: config.displayName };
+      records.push({ slug, projectId, config, state });
+    }
+    registry.updatedAt = new Date().toISOString();
+    validateRegistry(registry);
+    return { registry, records };
+  }
+
+  injectFault(options, stage) {
+    if (options && options.faultAt === stage) throw new Error(`injected migration fault: ${stage}`);
+  }
+
+  async migrateIfNeeded(options = {}) {
+    const existingCompletion = this.completion();
+    if (existingCompletion) {
+      const verified = this.validateCompletedState(existingCompletion);
+      if (!verified.ok) return { ok: false, migrated: false, completed: false, requiresManualRecovery: true, reason: verified.reason, error: verified.error };
+      if (existingCompletion.schema === 'layout-migration-completion/v2') return { ok: true, migrated: false, completed: true, marker: existingCompletion };
+      const marker = this.completionMarker({ runId: existingCompletion.runId || 'v1-marker-upgrade', registry: verified.registry, settings: verified.settings, modelsMigrated: fs.existsSync(this.layout.getCachePath('models')) });
+      this.atomic.writeJsonAtomic(this.layout.getMigrationCompletionPath(), marker);
+      return { ok: true, migrated: false, completed: true, marker };
+    }
+    const state = classifyDataState(this.legacyDataDir);
+    if (state.state === STATES.FRESH) return { ok: true, migrated: false, completed: false, reason: 'fresh-install' };
+    if (state.state === STATES.CORRUPT || state.state === STATES.MIGRATION_INCOMPLETE) {
+      return { ok: false, migrated: false, completed: false, requiresManualRecovery: true, reason: state.state.toLowerCase() };
+    }
+    const discovery = this.discover();
+    this.injectFault(options, 'discovery');
+    // A user may have configured only AI/embedding/knowledge settings before
+    // ever importing a project. That is still legacy user data and must be
+    // migrated into an explicitly empty v2 registry, never treated as Fresh.
+    const legacyProjects = safeReadJson(discovery.legacyProjectsPath, {});
+    if (legacyProjects && legacyProjects.schema === SCHEMAS.projectRegistry && legacyProjects.schemaVersion === 2 && fs.existsSync(this.layout.getSettingsPath())) {
+      validateRegistry(legacyProjects);
+      const settings = this.atomic.readJsonStrict(this.layout.getSettingsPath(), { category: 'settings' });
+      validateSettings(settings);
+      const marker = this.completionMarker({ runId: 'validated-existing-v2', registry: legacyProjects, settings, modelsMigrated: fs.existsSync(this.layout.getCachePath('models')) });
+      this.atomic.writeJsonAtomic(this.layout.getMigrationCompletionPath(), marker);
+      return { ok: true, migrated: false, completed: true, marker };
+    }
+    if (state.state !== STATES.LEGACY) return { ok: false, migrated: false, completed: false, requiresManualRecovery: true, reason: 'legacy-state-not-migratable' };
+
+    const migrationId = options.migrationRunId || `layout-v2-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
+    const recoveryDir = this.layout.getRecoveryPath(migrationId);
+    const backupDir = path.join(recoveryDir, 'backup');
+    const stagingDir = path.join(recoveryDir, 'staging');
+    fs.mkdirSync(backupDir, { recursive: true });
+    fs.mkdirSync(stagingDir, { recursive: true });
+    const journalPath = path.join(recoveryDir, 'journal.json');
+    const journal = {
+      schema: SCHEMAS.migrationJournal,
+      migrationId: SCHEMA_VERSIONS.layoutMigration,
+      runId: migrationId,
+      phase: 'discovered',
+      startedAt: new Date().toISOString(),
+      sources: discovery.sources,
+      activated: [],
+    };
+    this.atomic.writeJsonAtomic(journalPath, journal);
+    const legacyRegistryBackup = path.join(backupDir, 'projects.json');
+    try {
+      for (const entry of discovery.sources) {
+        const relative = path.relative(this.legacyDataDir, entry.path);
+        const safeRelative = relative.startsWith('..') || path.isAbsolute(relative)
+          ? path.join('external', hashBuffer(Buffer.from(entry.path)).slice(0, 16), path.basename(entry.path))
+          : relative;
+        copyRecursive(entry.path, path.join(backupDir, safeRelative));
+      }
+      journal.phase = 'backed-up';
+      this.atomic.writeJsonAtomic(journalPath, journal);
+      this.injectFault(options, 'backup');
+
+      const settings = this.mergeLegacySettings(discovery);
+      const projectData = this.buildProjectRecords(legacyProjects, settings);
+      const staged = [];
+      const stageJson = (relative, value) => {
+        const stagedPath = path.join(stagingDir, relative);
+        this.atomic.writeJsonAtomic(stagedPath, value);
+        staged.push({ relative, kind: 'file', hash: hashFile(stagedPath) });
+      };
+      stageJson('settings.json', settings);
+      for (const record of projectData.records) {
+        stageJson(path.join('projects', record.projectId, 'config.json'), record.config);
+        stageJson(path.join('projects', record.projectId, 'state.json'), record.state);
+      }
+      stageJson('projects.json', projectData.registry);
+      let modelsMigrated = false;
+      if (fs.existsSync(discovery.modelsPath)) {
+        const modelTarget = this.layout.getCachePath('models');
+        if (fs.existsSync(modelTarget)) {
+          if (directoryDigest(discovery.modelsPath) !== directoryDigest(modelTarget)) {
+            throw new DomainError('MIGRATION_TARGET_CONFLICT', 'Legacy model cache conflicts with the current model cache.', { status: 409, details: { category: 'cache/models' } });
+          }
+        } else {
+          const relative = path.join('cache', 'models');
+          copyRecursive(discovery.modelsPath, path.join(stagingDir, relative));
+          staged.push({ relative, kind: 'directory', hash: directoryDigest(path.join(stagingDir, relative)) });
+          modelsMigrated = true;
+        }
+      }
+      if (discovery.indexPath) {
+        const relative = path.join('index', 'knowledge.lancedb');
+        copyRecursive(discovery.indexPath, path.join(stagingDir, relative));
+        staged.push({ relative, kind: 'directory', hash: '' });
+      }
+      journal.staged = staged;
+      journal.projectMap = Object.fromEntries(projectData.records.map(record => [record.slug, record.projectId]));
+      journal.phase = 'staged';
+      this.atomic.writeJsonAtomic(journalPath, journal);
+      this.injectFault(options, 'staging');
+
+      if (!verifySourceSnapshot(discovery.sources)) throw new DomainError('MIGRATION_SOURCE_CHANGED', 'Migration source changed while staging.', { status: 409 });
+      validateSettings(JSON.parse(fs.readFileSync(path.join(stagingDir, 'settings.json'), 'utf8')));
+      validateRegistry(JSON.parse(fs.readFileSync(path.join(stagingDir, 'projects.json'), 'utf8')));
+      for (const record of projectData.records) {
+        validateProjectConfig(JSON.parse(fs.readFileSync(path.join(stagingDir, 'projects', record.projectId, 'config.json'), 'utf8')), record.projectId);
+        validateProjectState(JSON.parse(fs.readFileSync(path.join(stagingDir, 'projects', record.projectId, 'state.json'), 'utf8')));
+      }
+      if (discovery.indexPath) {
+        const indexResult = await this.indexValidator(path.join(stagingDir, 'index', 'knowledge.lancedb'));
+        if (!indexResult || indexResult.ok !== true) throw new DomainError('MIGRATION_FAILED', 'Staged index validation failed.', { status: 500 });
+      }
+      journal.phase = 'validated';
+      this.atomic.writeJsonAtomic(journalPath, journal);
+      this.injectFault(options, 'validation');
+
+      const activationOrder = staged.filter(item => item.relative !== 'projects.json');
+      const activationBackupDir = path.join(backupDir, 'activation-targets');
+      journal.activationTargets = activationOrder.map(item => {
+        const target = path.join(this.layout.getDataDir(), item.relative);
+        const existed = fs.existsSync(target);
+        if (item.kind === 'directory' && existed) {
+          throw new DomainError('MIGRATION_TARGET_CONFLICT', 'Migration target already exists.', { status: 409, details: { category: item.relative } });
+        }
+        if (existed) copyRecursive(target, path.join(activationBackupDir, item.relative));
+        return { relative: item.relative, kind: item.kind, existed };
+      });
+      this.atomic.writeJsonAtomic(journalPath, journal);
+      for (const item of activationOrder) {
+        const source = path.join(stagingDir, item.relative);
+        const target = path.join(this.layout.getDataDir(), item.relative);
+        if (item.kind === 'directory') {
+          copyRecursive(source, target);
+        } else {
+          this.atomic.writeFileAtomic(target, fs.readFileSync(source));
+        }
+        journal.activated.push(item.relative);
+        this.atomic.writeJsonAtomic(journalPath, journal);
+      }
+      this.atomic.writeFileAtomic(this.layout.getProjectRegistryPath(), fs.readFileSync(path.join(stagingDir, 'projects.json')));
+      journal.activated.push('projects.json');
+      journal.phase = 'activated';
+      this.atomic.writeJsonAtomic(journalPath, journal);
+      this.injectFault(options, 'activation');
+
+      validateSettings(this.atomic.readJsonStrict(this.layout.getSettingsPath(), { category: 'settings' }));
+      const openedRegistry = this.atomic.readJsonStrict(this.layout.getProjectRegistryPath(), { category: 'project-registry' });
+      validateRegistry(openedRegistry);
+      for (const projectId of openedRegistry.projectOrder) {
+        validateProjectConfig(this.atomic.readJsonStrict(this.layout.getProjectConfigPath(projectId), { category: 'project-config' }), projectId);
+        validateProjectState(this.atomic.readJsonStrict(this.layout.getProjectStatePath(projectId), { category: 'project-state' }));
+      }
+      journal.phase = 'open-verified';
+      this.atomic.writeJsonAtomic(journalPath, journal);
+      this.injectFault(options, 'open-verification');
+
+      const marker = this.completionMarker({ runId: migrationId, registry: openedRegistry, settings: this.atomic.readJsonStrict(this.layout.getSettingsPath(), { category: 'settings' }), modelsMigrated });
+      this.atomic.writeJsonAtomic(this.layout.getMigrationCompletionPath(), marker);
+      journal.phase = 'completed';
+      journal.completedAt = marker.completedAt;
+      this.atomic.writeJsonAtomic(journalPath, journal);
+      return { ok: true, migrated: true, completed: true, marker, recoveryDir, projectMap: journal.projectMap };
+    } catch (error) {
+      const rollbackErrors = [];
+      for (const targetInfo of [...(journal.activationTargets || [])].reverse()) {
+        const target = path.join(this.layout.getDataDir(), targetInfo.relative);
+        try {
+          if (targetInfo.existed) {
+            const backup = path.join(backupDir, 'activation-targets', targetInfo.relative);
+            if (targetInfo.kind === 'directory') {
+              removeOwnedPath(target);
+              copyRecursive(backup, target);
+            } else {
+              this.atomic.writeFileAtomic(target, fs.readFileSync(backup));
+            }
+          } else {
+            removeOwnedPath(target);
+            pruneEmptyParents(target, this.layout.getDataDir());
+          }
+        } catch (rollbackError) {
+          rollbackErrors.push({ target: targetInfo.relative, message: String(rollbackError.message || rollbackError) });
+        }
+      }
+      try {
+        if (fs.existsSync(legacyRegistryBackup)) {
+          this.atomic.writeFileAtomic(this.layout.getProjectRegistryPath(), fs.readFileSync(legacyRegistryBackup));
+        }
+      } catch (rollbackError) {
+        rollbackErrors.push({ target: 'projects.json', message: String(rollbackError.message || rollbackError) });
+      }
+      journal.phase = 'failed';
+      journal.failedAt = new Date().toISOString();
+      journal.error = { name: error.name || 'Error', code: error.code || '', message: String(error.message || error) };
+      journal.rollback = { ok: rollbackErrors.length === 0, errors: rollbackErrors };
+      this.atomic.writeJsonAtomic(journalPath, journal);
+      this.logger.error('migration.failed', { error, recoveryDir, rollbackErrors });
+      return { ok: false, migrated: false, completed: false, useLegacy: rollbackErrors.length === 0, recoveryDir, error, rollbackErrors };
+    }
+  }
+}
+
+module.exports = {
+  MigrationService,
+  deterministicProjectId,
+  hashFile,
+  sourceSnapshot,
+  verifySourceSnapshot,
+};