@sanqianx/project-knowledge 4.6.1

package/_site/lib/conversation-store.js

@@ -0,0 +1,385 @@
+const fs = require('fs');
+const crypto = require('crypto');
+const { SCHEMAS, DomainError, validateProjectId } = require('./contracts');
+const AtomicFile = require('./atomic-file');
+const { StorageLayout } = require('./storage-layout');
+
+const SOURCES = new Set(['claude-code', 'codex', 'opencode']);
+const ROLES = new Set(['user', 'assistant', null]);
+const SNAPSHOT_STATUSES = new Set(['available', 'no-new-user-prompt', 'unavailable', 'ambiguous']);
+const BINDING_KINDS = new Set(['direct', 'shared-spanning', 'explicit']);
+
+function sha256(value) {
+  return `sha256:${crypto.createHash('sha256').update(String(value == null ? '' : value), 'utf8').digest('hex')}`;
+}
+
+function optionalString(value) {
+  if (value == null || value === '') return null;
+  return String(value);
+}
+
+function validateConversationEvent(event, expectedProjectId = '') {
+  if (!event || typeof event !== 'object' || Array.isArray(event)) throw new DomainError('INVALID_ARGUMENT', 'Conversation event is invalid.');
+  if (event.schema !== SCHEMAS.aiCodingEvent) throw new DomainError('SCHEMA_UNSUPPORTED', 'Conversation event must use ai-coding-event/v1.', { status: 409 });
+  const projectId = validateProjectId(event.projectId);
+  if (expectedProjectId && projectId !== expectedProjectId) throw new DomainError('INVALID_ARGUMENT', 'Conversation event projectId does not match the store.');
+  if (!event.eventId || typeof event.eventId !== 'string') throw new DomainError('INVALID_ARGUMENT', 'Conversation eventId is required.');
+  if (event.sequence != null && (!Number.isInteger(event.sequence) || event.sequence < 0)) throw new DomainError('INVALID_ARGUMENT', 'Conversation sequence must be a non-negative integer or null.');
+  if (!SOURCES.has(event.source)) throw new DomainError('INVALID_ARGUMENT', 'Conversation source is invalid.');
+  if (!event.eventType || typeof event.eventType !== 'string') throw new DomainError('INVALID_ARGUMENT', 'Conversation eventType is required.');
+  if (!ROLES.has(event.role)) throw new DomainError('INVALID_ARGUMENT', 'Conversation role is invalid.');
+  if (event.role && typeof event.content !== 'string') throw new DomainError('INVALID_ARGUMENT', 'User and assistant events require text content.');
+  if (!event.capturedAt || Number.isNaN(Date.parse(event.capturedAt))) throw new DomainError('INVALID_ARGUMENT', 'Conversation capturedAt must be an ISO timestamp.');
+  if (event.contentHash !== sha256(event.content || '')) throw new DomainError('DATA_CORRUPT', 'Conversation content hash does not match.', { status: 409 });
+  return event;
+}
+
+function normalizeConversationEvent(projectId, input = {}) {
+  validateProjectId(projectId);
+  const role = input.role == null ? null : String(input.role);
+  const content = role ? String(input.content == null ? '' : input.content) : '';
+  const normalized = {
+    schema: SCHEMAS.aiCodingEvent,
+    projectId,
+    eventId: String(input.eventId || '').trim(),
+    sequence: input.sequence == null ? null : Number(input.sequence),
+    source: String(input.source || ''),
+    eventType: String(input.eventType || ''),
+    role,
+    content,
+    contentHash: sha256(content),
+    sessionId: optionalString(input.sessionId),
+    turnId: optionalString(input.turnId),
+    projectPath: optionalString(input.projectPath),
+    repoIdentity: input.repoIdentity && typeof input.repoIdentity === 'object' ? { ...input.repoIdentity } : null,
+    branch: optionalString(input.branch),
+    headAtCapture: optionalString(input.headAtCapture),
+    capturedAt: input.capturedAt || new Date().toISOString(),
+    rawEventType: optionalString(input.rawEventType),
+    identityConfidence: optionalString(input.identityConfidence) || 'unknown',
+    captureStatus: optionalString(input.captureStatus) || 'captured',
+    explicitCommitSha: optionalString(input.explicitCommitSha),
+    legacyRequirementId: optionalString(input.legacyRequirementId),
+  };
+  return validateConversationEvent(normalized, projectId);
+}
+
+function readJsonlStrict(filePath, validator, category) {
+  if (!fs.existsSync(filePath)) return [];
+  const records = [];
+  const lines = fs.readFileSync(filePath, 'utf8').split(/\r?\n/);
+  for (let index = 0; index < lines.length; index += 1) {
+    if (!lines[index].trim()) continue;
+    try {
+      records.push(validator(JSON.parse(lines[index])));
+    } catch (error) {
+      if (error instanceof DomainError) throw error;
+      throw new DomainError('DATA_CORRUPT', `${category} JSONL is corrupt.`, { status: 500, cause: error, details: { line: index + 1 } });
+    }
+  }
+  return records;
+}
+
+function appendJsonlDurable(filePath, value) {
+  fs.mkdirSync(require('path').dirname(filePath), { recursive: true });
+  const line = Buffer.from(`${JSON.stringify(value)}\n`, 'utf8');
+  const fd = fs.openSync(filePath, 'a', 0o600);
+  try {
+    fs.writeSync(fd, line, 0, line.length, null);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function validateBoundary(boundary, expectedProjectId = '', expectedCommitSha = '') {
+  if (!boundary || typeof boundary !== 'object' || boundary.schema !== SCHEMAS.gitCommitBoundary) {
+    throw new DomainError('SCHEMA_UNSUPPORTED', 'Commit boundary must use git-commit-boundary/v1.', { status: 409 });
+  }
+  validateProjectId(boundary.projectId);
+  if (expectedProjectId && boundary.projectId !== expectedProjectId) throw new DomainError('DATA_CORRUPT', 'Commit boundary projectId mismatch.', { status: 500 });
+  if (!boundary.commitSha || (expectedCommitSha && boundary.commitSha !== expectedCommitSha)) throw new DomainError('DATA_CORRUPT', 'Commit boundary SHA mismatch.', { status: 500 });
+  if (!Number.isInteger(boundary.bridgeCursorAtCommit) || boundary.bridgeCursorAtCommit < 0) throw new DomainError('INVALID_ARGUMENT', 'Commit boundary cursor is invalid.');
+  if (boundary.journalSequence != null && (!Number.isInteger(boundary.journalSequence) || boundary.journalSequence < 0)) throw new DomainError('INVALID_ARGUMENT', 'Commit boundary journal sequence is invalid.');
+  if (!Array.isArray(boundary.parentShas) || !Array.isArray(boundary.openTurnIdsAtCommit)) throw new DomainError('INVALID_ARGUMENT', 'Commit boundary collections are invalid.');
+  if (!boundary.operationId || !boundary.committedAt) throw new DomainError('INVALID_ARGUMENT', 'Commit boundary operation metadata is required.');
+  return boundary;
+}
+
+function snapshotPayload(snapshot) {
+  const { snapshotHash, ...payload } = snapshot;
+  return payload;
+}
+
+function validateSnapshot(snapshot, expectedProjectId = '', expectedCommitSha = '') {
+  if (!snapshot || typeof snapshot !== 'object' || snapshot.schema !== SCHEMAS.commitConversationSnapshot) {
+    throw new DomainError('SCHEMA_UNSUPPORTED', 'Commit conversation snapshot must use commit-conversation-snapshot/v1.', { status: 409 });
+  }
+  validateProjectId(snapshot.projectId);
+  if (expectedProjectId && snapshot.projectId !== expectedProjectId) throw new DomainError('DATA_CORRUPT', 'Conversation snapshot projectId mismatch.', { status: 500 });
+  if (!snapshot.commitSha || (expectedCommitSha && snapshot.commitSha !== expectedCommitSha)) throw new DomainError('DATA_CORRUPT', 'Conversation snapshot SHA mismatch.', { status: 500 });
+  if (!SNAPSHOT_STATUSES.has(snapshot.status) || !Array.isArray(snapshot.turns)) throw new DomainError('INVALID_ARGUMENT', 'Conversation snapshot status or turns are invalid.');
+  for (const turn of snapshot.turns) {
+    if (!turn.turnId || !BINDING_KINDS.has(turn.bindingKind) || !Array.isArray(turn.userEvents) || !Array.isArray(turn.assistantEvents)) {
+      throw new DomainError('INVALID_ARGUMENT', 'Conversation snapshot turn is invalid.');
+    }
+    for (const event of [...turn.userEvents, ...turn.assistantEvents]) {
+      if (!event.eventId || event.contentHash !== sha256(event.content || '')) throw new DomainError('DATA_CORRUPT', 'Snapshot event hash does not match.', { status: 409 });
+    }
+  }
+  if (snapshot.snapshotHash !== sha256(JSON.stringify(snapshotPayload(snapshot)))) throw new DomainError('DATA_CORRUPT', 'Conversation snapshot hash does not match.', { status: 409 });
+  return snapshot;
+}
+
+class ConversationStore {
+  constructor(options = {}) {
+    this.layout = options.layout || new StorageLayout(options);
+    this.atomic = options.atomic || AtomicFile;
+    this.projectStore = options.projectStore || null;
+    this.logger = options.logger || null;
+  }
+
+  async log(level, event, message, context) {
+    try {
+      if (this.logger && typeof this.logger[level] === 'function') await this.logger[level](event, message, context);
+    } catch {
+      // Conversation durability is independent from observer failures.
+    }
+  }
+
+  readEvents(projectId) {
+    validateProjectId(projectId);
+    return readJsonlStrict(
+      this.layout.getProjectConversationEventsPath(projectId),
+      event => validateConversationEvent(event, projectId),
+      'Conversation events',
+    );
+  }
+
+  async appendEvent(projectId, input) {
+    const event = normalizeConversationEvent(projectId, input);
+    const filePath = this.layout.getProjectConversationEventsPath(projectId);
+    const result = await this.atomic.withFileLock(`${filePath}.append.lock`, async () => {
+      const existing = this.readEvents(projectId).find(candidate => candidate.eventId === event.eventId);
+      if (existing) {
+        if (sha256(JSON.stringify(existing)) !== sha256(JSON.stringify(event))) {
+          throw new DomainError('DATA_CORRUPT', 'Duplicate conversation eventId has different content.', { status: 409 });
+        }
+        return { event: existing, appended: false };
+      }
+      appendJsonlDurable(filePath, event);
+      return { event, appended: true };
+    });
+    await this.log('info', result.appended ? 'conversation.event_appended' : 'conversation.event_deduplicated', 'Conversation event persisted.', {
+      projectId,
+      component: 'conversation-store',
+      context: {
+        eventId: event.eventId,
+        sequence: event.sequence,
+        source: event.source,
+        eventType: event.eventType,
+        role: event.role,
+        contentHash: event.contentHash,
+        contentLength: event.content.length,
+      },
+    });
+    return result;
+  }
+
+  _projectWorkspaceId(projectId) {
+    try {
+      const config = this.projectStore && typeof this.projectStore.readConfig === 'function'
+        ? this.projectStore.readConfig(projectId)
+        : null;
+      const identity = config && config.repoIdentity;
+      return identity && typeof identity === 'object' && typeof identity.workspaceId === 'string'
+        ? identity.workspaceId
+        : null;
+    } catch (_) {
+      return null;
+    }
+  }
+
+  /**
+   * Project-scoped projection of a canonical Bridge journal event. The global
+   * eventId / sequence / turnId / repoIdentity are preserved verbatim; a new
+   * local sequence is never assigned; dedup is by eventId with DATA_CORRUPT on
+   * content drift; an exact event whose workspaceId differs from the project's
+   * canonical workspace is rejected instead of contaminating the store.
+   */
+  async appendBridgeEvent(projectId, bridgeEvent) {
+    if (!bridgeEvent || typeof bridgeEvent !== 'object' || bridgeEvent.schema !== SCHEMAS.aiCodingEvent) {
+      throw new DomainError('SCHEMA_UNSUPPORTED', 'Bridge conversation event must use ai-coding-event/v1.', { status: 409 });
+    }
+    if (bridgeEvent.eventType !== 'user_prompt' && bridgeEvent.eventType !== 'assistant_response') {
+      throw new DomainError('INVALID_ARGUMENT', 'Bridge conversation event must be a user_prompt or assistant_response.');
+    }
+    if (!bridgeEvent.eventId || typeof bridgeEvent.eventId !== 'string') {
+      throw new DomainError('INVALID_ARGUMENT', 'Bridge eventId is required.');
+    }
+    if (!Number.isInteger(bridgeEvent.sequence) || bridgeEvent.sequence < 0) {
+      throw new DomainError('INVALID_ARGUMENT', 'Bridge sequence is required for projected events.');
+    }
+    const configWorkspaceId = this._projectWorkspaceId(projectId);
+    const eventIdentity = bridgeEvent.repoIdentity;
+    const eventWorkspaceId = eventIdentity && typeof eventIdentity === 'object' && typeof eventIdentity.workspaceId === 'string'
+      ? eventIdentity.workspaceId
+      : null;
+    if (configWorkspaceId && eventWorkspaceId && configWorkspaceId !== eventWorkspaceId) {
+      throw new DomainError('DATA_CORRUPT', 'Bridge event workspaceId does not match the project workspace.', { status: 409 });
+    }
+    return this.appendEvent(projectId, {
+      eventId: bridgeEvent.eventId,
+      sequence: bridgeEvent.sequence,
+      source: bridgeEvent.source,
+      eventType: bridgeEvent.eventType,
+      role: bridgeEvent.role,
+      content: bridgeEvent.content == null ? '' : bridgeEvent.content,
+      sessionId: bridgeEvent.sessionId,
+      turnId: bridgeEvent.turnId,
+      projectPath: bridgeEvent.projectPath,
+      repoIdentity: eventIdentity,
+      branch: bridgeEvent.branch,
+      headAtCapture: bridgeEvent.headAtCapture,
+      capturedAt: bridgeEvent.capturedAt,
+      rawEventType: bridgeEvent.rawEventType,
+      identityConfidence: bridgeEvent.identityConfidence,
+      captureStatus: bridgeEvent.captureStatus,
+    });
+  }
+
+  legacyRequirementToEvent(projectId, requirement) {
+    if (!requirement || requirement.schema !== SCHEMAS.requirement || requirement.projectId !== projectId || !requirement.id) {
+      throw new DomainError('INVALID_ARGUMENT', 'Legacy requirement record is invalid.');
+    }
+    const source = requirement.client === 'claude' ? 'claude-code' : requirement.client;
+    return normalizeConversationEvent(projectId, {
+      eventId: `legacy-${requirement.id}`,
+      sequence: null,
+      source: SOURCES.has(source) ? source : 'codex',
+      eventType: 'user_prompt',
+      role: 'user',
+      content: requirement.requirement,
+      sessionId: requirement.sessionId,
+      turnId: `legacy-${requirement.id}`,
+      projectPath: requirement.repoPath,
+      repoIdentity: requirement.repoIdentity || null,
+      branch: requirement.branch,
+      headAtCapture: requirement.headAtRecord,
+      capturedAt: requirement.ts,
+      rawEventType: 'legacy-requirement',
+      identityConfidence: requirement.explicitCommit ? 'explicit' : 'legacy',
+      captureStatus: 'legacy-explicit-adapter',
+      explicitCommitSha: requirement.explicitCommit,
+      legacyRequirementId: requirement.id,
+    });
+  }
+
+  async importLegacyRequirements(projectId, records = null) {
+    const requirements = records || (this.projectStore ? this.projectStore.readRequirements(projectId) : []);
+    const results = [];
+    for (const requirement of requirements) results.push(await this.appendEvent(projectId, this.legacyRequirementToEvent(projectId, requirement)));
+    return results;
+  }
+
+  writeBoundary(projectId, boundaryInput) {
+    const commitSha = this.layout.validateCommitSha(boundaryInput.commitSha);
+    const boundary = validateBoundary({
+      schema: SCHEMAS.gitCommitBoundary,
+      projectId,
+      repoIdentity: boundaryInput.repoIdentity || null,
+      commitSha,
+      parentShas: Array.isArray(boundaryInput.parentShas) ? boundaryInput.parentShas.map(value => String(value).toLowerCase()) : [],
+      branch: optionalString(boundaryInput.branch),
+      committedAt: boundaryInput.committedAt || new Date().toISOString(),
+      bridgeCursorAtCommit: Number(boundaryInput.bridgeCursorAtCommit),
+      openTurnIdsAtCommit: Array.isArray(boundaryInput.openTurnIdsAtCommit) ? [...new Set(boundaryInput.openTurnIdsAtCommit.map(String))] : [],
+      operationId: String(boundaryInput.operationId || ''),
+      journalSequence: Number.isInteger(boundaryInput.journalSequence) ? boundaryInput.journalSequence : Number(boundaryInput.bridgeCursorAtCommit),
+      boundaryHash: '',
+    }, projectId, commitSha);
+    boundary.boundaryHash = sha256(JSON.stringify({ ...boundary, boundaryHash: undefined }));
+    const filePath = this.layout.getProjectCommitBoundaryPath(projectId, commitSha);
+    if (fs.existsSync(filePath)) {
+      const existing = this.readBoundary(projectId, commitSha);
+      if (existing.boundaryHash !== boundary.boundaryHash) throw new DomainError('DATA_CORRUPT', 'Conflicting evidence was supplied for an existing commit boundary.', { status: 409 });
+      return existing;
+    }
+    this.atomic.writeJsonAtomic(filePath, boundary);
+    return boundary;
+  }
+
+  readBoundary(projectId, commitSha) {
+    const normalizedSha = this.layout.validateCommitSha(commitSha);
+    return this.atomic.readJsonStrict(this.layout.getProjectCommitBoundaryPath(projectId, normalizedSha), {
+      category: 'git-commit-boundary',
+      validate: value => validateBoundary(value, projectId, normalizedSha),
+    });
+  }
+
+  listBoundaries(projectId) {
+    validateProjectId(projectId);
+    const directory = this.layout.getProjectCommitBoundariesDir(projectId);
+    if (!fs.existsSync(directory)) return [];
+    return fs.readdirSync(directory, { withFileTypes: true })
+      .filter(entry => entry.isFile() && /^[a-f0-9]{7,64}\.json$/i.test(entry.name))
+      .map(entry => this.readBoundary(projectId, entry.name.slice(0, -5)));
+  }
+
+  writeSnapshot(projectId, input) {
+    const commitSha = this.layout.validateCommitSha(input.commitSha);
+    const snapshot = {
+      schema: SCHEMAS.commitConversationSnapshot,
+      projectId,
+      repoIdentity: input.repoIdentity || null,
+      commitSha,
+      parentSha: input.parentSha || null,
+      boundaryStartCursor: input.boundaryStartCursor == null ? null : Number(input.boundaryStartCursor),
+      boundaryEndCursor: input.boundaryEndCursor == null ? null : Number(input.boundaryEndCursor),
+      status: input.status,
+      turns: input.turns || [],
+      excludedFuturePromptCount: Number(input.excludedFuturePromptCount || 0),
+      finalizedAt: input.finalizedAt || new Date().toISOString(),
+      snapshotHash: '',
+    };
+    snapshot.snapshotHash = sha256(JSON.stringify(snapshotPayload(snapshot)));
+    validateSnapshot(snapshot, projectId, commitSha);
+    const filePath = this.layout.getProjectCommitConversationPath(projectId, commitSha);
+    if (fs.existsSync(filePath)) {
+      const existing = this.readSnapshot(projectId, commitSha);
+      if (existing.snapshotHash !== snapshot.snapshotHash) throw new DomainError('IMMUTABLE_FIELD', 'Commit conversation snapshot is already frozen.', { status: 409 });
+      return existing;
+    }
+    this.atomic.writeJsonAtomic(filePath, snapshot);
+    return snapshot;
+  }
+
+  readSnapshot(projectId, commitSha) {
+    const normalizedSha = this.layout.validateCommitSha(commitSha);
+    return this.atomic.readJsonStrict(this.layout.getProjectCommitConversationPath(projectId, normalizedSha), {
+      category: 'commit-conversation-snapshot',
+      validate: value => validateSnapshot(value, projectId, normalizedSha),
+    });
+  }
+
+  listSnapshots(projectId) {
+    validateProjectId(projectId);
+    const directory = this.layout.getProjectCommitConversationsDir(projectId);
+    if (!fs.existsSync(directory)) return [];
+    return fs.readdirSync(directory, { withFileTypes: true })
+      .filter(entry => entry.isFile() && /^[a-f0-9]{7,64}\.json$/i.test(entry.name))
+      .map(entry => this.readSnapshot(projectId, entry.name.slice(0, -5)));
+  }
+}
+
+module.exports = {
+  ConversationStore,
+  SOURCES,
+  SNAPSHOT_STATUSES,
+  BINDING_KINDS,
+  sha256,
+  normalizeConversationEvent,
+  validateConversationEvent,
+  validateBoundary,
+  validateSnapshot,
+};

package/_site/lib/data-dir.js

@@ -0,0 +1,81 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+const { LEGACY_ASSETS, assetPath } = require('./legacy-data-manifest');
+const { isEmptyJson } = require('./data-state-classifier');
+
+let _resolved = null;
+
+function resolveDataDirPath(options = {}) {
+  const fromEnv = options.dataDir === undefined ? process.env.KB_DATA_DIR : options.dataDir;
+  const homeDir = options.homeDir || os.homedir();
+  return path.resolve(fromEnv || path.join(homeDir, '.project-knowledge'));
+}
+function ensureDataDir(dataDir = resolveDataDirPath()) { fs.mkdirSync(dataDir, { recursive: true }); return path.resolve(dataDir); }
+function getDataDir() { if (!_resolved) _resolved = resolveDataDirPath(); return _resolved; }
+function _resetCache() { _resolved = null; }
+function fileDigest(filePath) { return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex'); }
+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 filePath = path.join(current, entry.name);
+      const relative = path.relative(root, filePath).replace(/\\/g, '/');
+      hash.update(`${entry.isDirectory() ? 'd' : 'f'}:${relative}\0`);
+      if (entry.isDirectory()) walk(filePath); else if (entry.isFile()) hash.update(fs.readFileSync(filePath));
+    }
+  };
+  walk(root); return hash.digest('hex');
+}
+function isEmptyAsset(filePath, asset) {
+  if (!fs.existsSync(filePath)) return true;
+  if (asset.kind === 'dir') return fs.readdirSync(filePath).length === 0;
+  if (fs.statSync(filePath).size === 0) return true;
+  if (!filePath.endsWith('.json')) return false;
+  try { const raw = fs.readFileSync(filePath, 'utf8'); return isEmptyJson(JSON.parse(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw)); } catch { return false; }
+}
+function assetsEqual(source, target, asset) { return asset.kind === 'dir' ? directoryDigest(source) === directoryDigest(target) : fileDigest(source) === fileDigest(target); }
+function copyDir(source, target) {
+  fs.mkdirSync(target, { recursive: true });
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    const from = path.join(source, entry.name); const to = path.join(target, entry.name);
+    if (entry.isDirectory()) copyDir(from, to); else if (entry.isFile()) fs.copyFileSync(from, to);
+  }
+}
+
+function migrateFromLegacy({ legacyRoot, logger } = {}) {
+  if (process.env.KB_SKIP_MIGRATION === '1') return { ok: true, migrated: false, reason: 'skipped via KB_SKIP_MIGRATION=1' };
+  if (!legacyRoot || !fs.existsSync(legacyRoot)) return { ok: true, migrated: false, reason: legacyRoot ? 'legacy root does not exist' : 'no legacy root provided' };
+  const dataDir = getDataDir();
+  if (path.resolve(legacyRoot) === dataDir) return { ok: true, migrated: false, reason: 'legacy root equals data dir' };
+  // Packaged application roots may include empty scaffolding such as
+  // `projects/`. It is not user data and must never conflict with populated
+  // runtime data during startup relocation.
+  const sources = LEGACY_ASSETS.filter(asset => {
+    const source = assetPath(legacyRoot, asset);
+    return fs.existsSync(source) && !isEmptyAsset(source, asset);
+  });
+  if (!sources.length) return { ok: true, migrated: false, reason: 'no legacy assets found' };
+  const conflicts = [];
+  for (const asset of sources) {
+    const source = assetPath(legacyRoot, asset); const target = assetPath(dataDir, asset, 'target');
+    if (fs.existsSync(target) && !isEmptyAsset(target, asset) && !assetsEqual(source, target, asset)) conflicts.push(asset.target);
+  }
+  if (conflicts.length) return { ok: false, migrated: false, requiresManualRecovery: true, reason: 'legacy-data-conflict', conflicts, source: legacyRoot, target: dataDir };
+  ensureDataDir(dataDir);
+  const result = { ok: true, migrated: false, files: 0, dirs: 0, source: legacyRoot, target: dataDir };
+  try {
+    for (const asset of sources) {
+      const source = assetPath(legacyRoot, asset); const target = assetPath(dataDir, asset, 'target');
+      if (fs.existsSync(target) && assetsEqual(source, target, asset)) continue;
+      if (asset.kind === 'dir') { if (fs.existsSync(target)) fs.rmSync(target, { recursive: true, force: true }); copyDir(source, target); result.dirs++; }
+      else { fs.mkdirSync(path.dirname(target), { recursive: true }); fs.copyFileSync(source, target); result.files++; }
+    }
+    result.migrated = result.files > 0 || result.dirs > 0;
+    if (result.migrated && logger) logger(`migrated runtime data to ${dataDir} (${result.files} files, ${result.dirs} dirs from ${legacyRoot})`);
+    return result;
+  } catch (error) { return { ...result, ok: false, error: `failed to relocate legacy runtime data: ${error.message}` }; }
+}
+
+module.exports = { resolveDataDirPath, ensureDataDir, getDataDir, migrateFromLegacy, LEGACY_ASSETS, _resetCache };

package/_site/lib/data-state-classifier.js

@@ -0,0 +1,40 @@
+const fs = require('fs');
+const path = require('path');
+const { SCHEMAS } = require('./contracts');
+const { LEGACY_ASSETS, assetPath } = require('./legacy-data-manifest');
+
+const STATES = Object.freeze({ FRESH: 'FRESH', LEGACY: 'LEGACY', V2_VALID: 'V2_VALID', MIGRATION_INCOMPLETE: 'MIGRATION_INCOMPLETE', CONFLICT: 'CONFLICT', CORRUPT: 'CORRUPT' });
+
+function readJson(filePath) {
+  if (!fs.existsSync(filePath)) return { exists: false, value: null };
+  try { const raw = fs.readFileSync(filePath, 'utf8'); return { exists: true, value: JSON.parse(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw) }; }
+  catch (error) { return { exists: true, error }; }
+}
+function isEmptyJson(value) {
+  if (value == null || typeof value !== 'object') return false;
+  if (Array.isArray(value)) return value.length === 0;
+  if (value.schema === SCHEMAS.projectRegistry) return Array.isArray(value.projectOrder) && value.projectOrder.length === 0;
+  return Object.keys(value).length === 0;
+}
+function hasRecovery(root) { const recovery = path.join(root, 'recovery'); return fs.existsSync(recovery) && fs.statSync(recovery).isDirectory() && fs.readdirSync(recovery).length > 0; }
+function classifyDataState(root) {
+  const projects = readJson(path.join(root, 'projects.json'));
+  const settings = readJson(path.join(root, 'settings.json'));
+  if (projects.error || settings.error) return { state: STATES.CORRUPT, projects, settings };
+  // Logs and hook diagnostics can be created before startup classification;
+  // alone they are not user configuration evidence and must not turn a clean
+  // install into an impossible legacy migration.
+  const hasLegacyAssets = LEGACY_ASSETS.some(asset => asset.authority !== 'history' && fs.existsSync(assetPath(root, asset)));
+  const isV2 = projects.value && projects.value.schema === SCHEMAS.projectRegistry && projects.value.schemaVersion === 2;
+  const settingsV2 = settings.value && settings.value.schema === SCHEMAS.settings && settings.value.schemaVersion === 2;
+  if (isV2 && settingsV2) return { state: STATES.V2_VALID, projects, settings, hasLegacyAssets };
+  // A failed migration may have written default v2 settings before activation.
+  // A non-v2 projects registry remains authoritative legacy evidence and is
+  // eligible for a controlled retry; it must never be classified as Fresh.
+  if (projects.exists && !isV2 && hasLegacyAssets) return { state: STATES.LEGACY, projects, settings, hasLegacyAssets };
+  if (isV2 || settingsV2 || hasRecovery(root)) return { state: STATES.MIGRATION_INCOMPLETE, projects, settings, hasLegacyAssets };
+  if (hasLegacyAssets) return { state: STATES.LEGACY, projects, settings, hasLegacyAssets };
+  return { state: STATES.FRESH, projects, settings, hasLegacyAssets };
+}
+
+module.exports = { STATES, readJson, isEmptyJson, classifyDataState };

package/_site/lib/embedding-service.js

@@ -0,0 +1,85 @@
+const path = require('path');
+const { EMBEDDING_DIMENSIONS } = require('./knowledge-schema');
+
+const DEFAULT_MODEL_ID = 'Xenova/bge-small-zh-v1.5';
+const QUERY_PREFIX = '为这个句子生成表示以用于检索相关文章：';
+
+class LocalEmbeddingService {
+  constructor(options = {}) {
+    this.modelId = options.modelId || DEFAULT_MODEL_ID;
+    this.cacheDir = options.cacheDir ? path.resolve(options.cacheDir) : null;
+    this.remoteHost = String(options.remoteHost || process.env.KB_EMBEDDING_REMOTE_HOST || process.env.HF_ENDPOINT || 'https://huggingface.co/').trim();
+    this.localModelPath = options.localModelPath || process.env.KB_EMBEDDING_LOCAL_PATH || '';
+    this.localFilesOnly = options.localFilesOnly === true;
+    this.pipelineFactory = options.pipelineFactory || null;
+    this.extractor = null;
+    this.loading = null;
+  }
+
+  async load() {
+    if (this.extractor) return this.extractor;
+    if (this.loading) return this.loading;
+    this.loading = (async () => {
+      let pipelineFactory = this.pipelineFactory;
+      if (!pipelineFactory) {
+        const transformers = await import('@huggingface/transformers');
+        if (this.cacheDir) transformers.env.cacheDir = this.cacheDir;
+        if (this.remoteHost) transformers.env.remoteHost = `${this.remoteHost.replace(/\/+$/, '')}/`;
+        if (this.localModelPath) transformers.env.localModelPath = path.resolve(this.localModelPath);
+        transformers.env.allowRemoteModels = !this.localFilesOnly;
+        pipelineFactory = transformers.pipeline;
+      }
+      const extractor = await pipelineFactory('feature-extraction', this.modelId, {
+        dtype: 'fp32',
+        local_files_only: this.localFilesOnly,
+      });
+      this.extractor = extractor;
+      return extractor;
+    })();
+    try {
+      return await this.loading;
+    } catch (error) {
+      const hint = this.localFilesOnly
+        ? `Local model files were not found. Set KB_EMBEDDING_LOCAL_PATH to a directory containing ${this.modelId}.`
+        : `Could not load ${this.modelId} from ${this.remoteHost}. Check the network, or set KB_EMBEDDING_REMOTE_HOST / KB_EMBEDDING_LOCAL_PATH.`;
+      throw new Error(`${hint} ${error.message}`, { cause: error });
+    } finally {
+      this.loading = null;
+    }
+  }
+
+  async embed(text, options = {}) {
+    const normalized = String(text || '').trim();
+    if (!normalized) throw new Error('text is required for embedding');
+    const extractor = await this.load();
+    const input = options.kind === 'query' ? `${QUERY_PREFIX}${normalized}` : normalized;
+    const output = await extractor(input, { pooling: 'cls', normalize: true });
+    const vector = Array.from(output.data || output.tolist?.()[0] || [], Number);
+    if (vector.length !== EMBEDDING_DIMENSIONS) {
+      throw new Error(`embedding model returned ${vector.length} dimensions; expected ${EMBEDDING_DIMENSIONS}`);
+    }
+    return vector;
+  }
+
+  embedQuery(text) {
+    return this.embed(text, { kind: 'query' });
+  }
+
+  embedPassage(text) {
+    return this.embed(text, { kind: 'passage' });
+  }
+
+  status() {
+    return {
+      modelId: this.modelId,
+      dimensions: EMBEDDING_DIMENSIONS,
+      cacheDir: this.cacheDir,
+      remoteHost: this.remoteHost,
+      localModelPath: this.localModelPath || null,
+      loaded: !!this.extractor,
+      localFilesOnly: this.localFilesOnly,
+    };
+  }
+}
+
+module.exports = { LocalEmbeddingService, DEFAULT_MODEL_ID, QUERY_PREFIX };