@sanqianx/project-knowledge 4.7.0 → 5.0.0

package/_site/lib/settings-store.js

@@ -1,113 +1,133 @@
-const { SCHEMAS, DomainError, publicAiProfilesConfig } = require('./contracts');
-const AtomicFile = require('./atomic-file');
-const { StorageLayout } = require('./storage-layout');
-
-function defaultSettings() {
-  return {
-    schema: SCHEMAS.settings,
-    schemaVersion: 2,
-    knowledge: { rootPath: '' },
-    ai: { schema: 'ai-profiles/v1', profiles: [] },
-    embedding: {},
-    logging: {
-      levels: ['trace', 'debug', 'info', 'warn', 'error', 'fatal'],
-    },
-    promptOverrides: {},
-    integrations: {},
-    legacyExtensions: {},
-    updatedAt: '',
-  };
-}
-
-function mergeObjects(base, patch) {
-  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) return patch;
-  const output = { ...(base && typeof base === 'object' && !Array.isArray(base) ? base : {}) };
-  for (const [key, value] of Object.entries(patch)) {
-    output[key] = value && typeof value === 'object' && !Array.isArray(value)
-      ? mergeObjects(output[key], value)
-      : value;
-  }
-  return output;
-}
-
-function validateSettings(settings) {
-  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
-    throw new DomainError('DATA_CORRUPT', 'Settings must be an object.', { status: 500 });
-  }
-  if (settings.schema !== SCHEMAS.settings || settings.schemaVersion !== 2) {
-    throw new DomainError('SCHEMA_UNSUPPORTED', 'Unsupported settings schema.', { status: 409 });
-  }
-  if (!settings.knowledge || typeof settings.knowledge.rootPath !== 'string') {
-    throw new DomainError('DATA_CORRUPT', 'Settings knowledge.rootPath is invalid.', { status: 500 });
-  }
-  const logging = settings.logging || {};
-  if (!Array.isArray(logging.levels) || !logging.levels.length || logging.levels.some(level => !['trace', 'debug', 'info', 'warn', 'error', 'fatal'].includes(level))) {
-    throw new DomainError('DATA_CORRUPT', 'Settings logging configuration is invalid.', { status: 500 });
-  }
-  return settings;
-}
-
-class SettingsStore {
-  constructor(options = {}) {
-    this.layout = options.layout || new StorageLayout(options);
-    this.atomic = options.atomic || AtomicFile;
-    this.filePath = options.filePath || this.layout.getSettingsPath();
-    this.lockPath = options.lockPath || this.layout.getRuntimePath('locks', 'settings.lock');
-  }
-
-  read(options = {}) {
-    if (options.allowMissing) {
-      return this.atomic.readJsonStrict(this.filePath, {
-        allowMissing: true,
-        defaultValue: defaultSettings(),
-        category: 'settings',
-        validate: validateSettings,
-      });
-    }
-    return this.atomic.readJsonStrict(this.filePath, { category: 'settings', validate: validateSettings });
-  }
-
-  async initialize(initial = {}) {
-    return this.atomic.withFileLock(this.lockPath, async () => {
-      let current;
-      try { current = this.read(); }
-      catch (error) {
-        if (!error || error.code !== 'ENOENT') throw error;
-      }
-      if (current) return current;
-      const next = validateSettings(mergeObjects(defaultSettings(), initial));
-      next.updatedAt = new Date().toISOString();
-      this.atomic.writeJsonAtomic(this.filePath, next);
-      return next;
-    });
-  }
-
-  async updatePatch(patch) {
-    return this.atomic.withFileLock(this.lockPath, async () => {
-      if (patch && patch.logging && typeof patch.logging === 'object') {
-        const unknown = Object.keys(patch.logging).find(key => key !== 'levels');
-        if (unknown) throw new DomainError('INVALID_ARGUMENT', `Logging setting is read-only or unsupported: ${unknown}.`, { details: { field: unknown } });
-      }
-      const current = this.read({ allowMissing: true });
-      const next = mergeObjects(current, patch || {});
-      next.schema = SCHEMAS.settings;
-      next.schemaVersion = 2;
-      next.updatedAt = new Date().toISOString();
-      validateSettings(next);
-      if (next.knowledge.rootPath) this.layout.validateKnowledgeRoot(next.knowledge.rootPath);
-      this.atomic.writeJsonAtomic(this.filePath, next);
-      return next;
-    });
-  }
-
-  readPublicView(options = {}) {
-    const settings = this.read(options);
-    return {
-      ...settings,
-      ai: publicAiProfilesConfig(settings.ai),
-      logging: { levels: [...settings.logging.levels] },
-    };
-  }
-}
-
-module.exports = { SettingsStore, defaultSettings, validateSettings, mergeObjects };
+const { SCHEMAS, DomainError, publicAiProfilesConfig } = require('./contracts');
+const AtomicFile = require('./atomic-file');
+const { StorageLayout } = require('./storage-layout');
+
+function defaultSettings() {
+  return {
+    schema: SCHEMAS.settings,
+    schemaVersion: 2,
+    knowledge: { rootPath: '' },
+    brain: { id: 'brain-default', name: '我的智脑', domains: [] },
+    ai: { schema: 'ai-profiles/v1', profiles: [] },
+    embedding: {},
+    logging: {
+      levels: ['trace', 'debug', 'info', 'warn', 'error', 'fatal'],
+    },
+    promptOverrides: {},
+    integrations: {},
+    legacyExtensions: {},
+    updatedAt: '',
+  };
+}
+
+function mergeObjects(base, patch) {
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) return patch;
+  const output = { ...(base && typeof base === 'object' && !Array.isArray(base) ? base : {}) };
+  for (const [key, value] of Object.entries(patch)) {
+    output[key] = value && typeof value === 'object' && !Array.isArray(value)
+      ? mergeObjects(output[key], value)
+      : value;
+  }
+  return output;
+}
+
+function validateSettings(settings) {
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+    throw new DomainError('DATA_CORRUPT', 'Settings must be an object.', { status: 500 });
+  }
+  if (settings.schema !== SCHEMAS.settings || settings.schemaVersion !== 2) {
+    throw new DomainError('SCHEMA_UNSUPPORTED', 'Unsupported settings schema.', { status: 409 });
+  }
+  if (!settings.knowledge || typeof settings.knowledge.rootPath !== 'string') {
+    throw new DomainError('DATA_CORRUPT', 'Settings knowledge.rootPath is invalid.', { status: 500 });
+  }
+  settings.brain = settings.brain || { id: 'brain-default', name: '我的智脑', domains: [] };
+  if (settings.brain.id !== 'brain-default' || typeof settings.brain.name !== 'string' || !settings.brain.name.trim() || settings.brain.name.length > 100 || !Array.isArray(settings.brain.domains)) throw new DomainError('DATA_CORRUPT', 'Brain metadata is invalid.', { status: 500 });
+  const ids = new Set();
+  for (const domain of settings.brain.domains) {
+    if (!domain || !/^domain-[a-z0-9-]+$/.test(domain.id) || ids.has(domain.id) || typeof domain.name !== 'string' || !domain.name.trim() || domain.name.length > 100) throw new DomainError('DATA_CORRUPT', 'Domain metadata is invalid.', { status: 500 });
+    ids.add(domain.id);
+  }
+  const logging = settings.logging || {};
+  if (!Array.isArray(logging.levels) || !logging.levels.length || logging.levels.some(level => !['trace', 'debug', 'info', 'warn', 'error', 'fatal'].includes(level))) {
+    throw new DomainError('DATA_CORRUPT', 'Settings logging configuration is invalid.', { status: 500 });
+  }
+  return settings;
+}
+
+class SettingsStore {
+  constructor(options = {}) {
+    this.layout = options.layout || new StorageLayout(options);
+    this.atomic = options.atomic || AtomicFile;
+    this.filePath = options.filePath || this.layout.getSettingsPath();
+    this.lockPath = options.lockPath || this.layout.getRuntimePath('locks', 'settings.lock');
+  }
+
+  read(options = {}) {
+    if (options.allowMissing) {
+      return this.atomic.readJsonStrict(this.filePath, {
+        allowMissing: true,
+        defaultValue: defaultSettings(),
+        category: 'settings',
+        validate: validateSettings,
+      });
+    }
+    return this.atomic.readJsonStrict(this.filePath, { category: 'settings', validate: validateSettings });
+  }
+
+  async initialize(initial = {}) {
+    return this.atomic.withFileLock(this.lockPath, async () => {
+      let current;
+      try { current = this.read(); }
+      catch (error) {
+        if (!error || error.code !== 'ENOENT') throw error;
+      }
+      if (current) return current;
+      const next = validateSettings(mergeObjects(defaultSettings(), initial));
+      next.updatedAt = new Date().toISOString();
+      this.atomic.writeJsonAtomic(this.filePath, next);
+      return next;
+    });
+  }
+
+  async updatePatch(patch) {
+    return this.atomic.withFileLock(this.lockPath, async () => {
+      if (patch && patch.logging && typeof patch.logging === 'object') {
+        const unknown = Object.keys(patch.logging).find(key => key !== 'levels');
+        if (unknown) throw new DomainError('INVALID_ARGUMENT', `Logging setting is read-only or unsupported: ${unknown}.`, { details: { field: unknown } });
+      }
+      const current = this.read({ allowMissing: true });
+      const next = mergeObjects(current, patch || {});
+      next.schema = SCHEMAS.settings;
+      next.schemaVersion = 2;
+      next.updatedAt = new Date().toISOString();
+      validateSettings(next);
+      if (next.knowledge.rootPath) this.layout.validateKnowledgeRoot(next.knowledge.rootPath);
+      this.atomic.writeJsonAtomic(this.filePath, next);
+      return next;
+    });
+  }
+
+  async addDomain(domain) {
+    return this.atomic.withFileLock(this.lockPath, async () => {
+      const settings = this.read();
+      if (settings.brain.domains.some(d => d.name === domain.name || d.id === domain.id)) throw new DomainError('INVALID_ARGUMENT', '领域已存在。', { status: 409 });
+      settings.brain.domains.push(domain);
+      settings.updatedAt = new Date().toISOString();
+      validateSettings(settings);
+      this.atomic.writeJsonAtomic(this.filePath, settings);
+      return domain;
+    });
+  }
+
+  readPublicView(options = {}) {
+    const settings = this.read(options);
+    return {
+      ...settings,
+      ai: publicAiProfilesConfig(settings.ai),
+      logging: { levels: [...settings.logging.levels] },
+    };
+  }
+}
+
+module.exports = { SettingsStore, defaultSettings, validateSettings, mergeObjects };

package/_site/lib/storage-layout.js

@@ -1,162 +1,162 @@
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const crypto = require('crypto');
-const dataDirModule = require('./data-dir');
-const { DomainError, validateProjectId } = require('./contracts');
-
-function stripTrailingSeparators(value) {
-  const parsed = path.parse(value);
-  let result = value;
-  while (result.length > parsed.root.length && /[\\/]$/.test(result)) result = result.slice(0, -1);
-  return result;
-}
-
-class StorageLayout {
-  constructor(options = {}) {
-    this.dataDir = path.resolve(options.dataDir || dataDirModule.getDataDir());
-    this.platform = options.platform || process.platform;
-  }
-
-  getDataDir() { return this.dataDir; }
-  getSettingsPath() { return path.join(this.dataDir, 'settings.json'); }
-  getProjectRegistryPath() { return path.join(this.dataDir, 'projects.json'); }
-  getMigrationStatePath() { return path.join(this.dataDir, 'runtime', 'migration-state.json'); }
-  getMigrationCompletionPath() { return path.join(this.dataDir, 'runtime', 'layout-v2.completed.json'); }
-
-  getProjectMetadataDir(projectId) {
-    return path.join(this.dataDir, 'projects', validateProjectId(projectId));
-  }
-
-  getProjectConfigPath(projectId) { return path.join(this.getProjectMetadataDir(projectId), 'config.json'); }
-  getProjectStatePath(projectId) { return path.join(this.getProjectMetadataDir(projectId), 'state.json'); }
-  getProjectRequirementsPath(projectId) { return path.join(this.getProjectMetadataDir(projectId), 'requirements.jsonl'); }
-  getProjectConversationEventsPath(projectId) { return path.join(this.getProjectMetadataDir(projectId), 'conversation-events.jsonl'); }
-  getProjectCommitBoundariesDir(projectId) { return path.join(this.getProjectMetadataDir(projectId), 'commit-boundaries'); }
-  getProjectCommitConversationsDir(projectId) { return path.join(this.getProjectMetadataDir(projectId), 'commit-conversations'); }
-  validateCommitSha(commitSha) {
-    const value = String(commitSha || '').trim().toLowerCase();
-    if (!/^[a-f0-9]{7,64}$/.test(value)) throw new DomainError('INVALID_ARGUMENT', 'Invalid commit SHA.');
-    return value;
-  }
-  getProjectCommitBoundaryPath(projectId, commitSha) {
-    return path.join(this.getProjectCommitBoundariesDir(projectId), `${this.validateCommitSha(commitSha)}.json`);
-  }
-  getProjectCommitConversationPath(projectId, commitSha) {
-    return path.join(this.getProjectCommitConversationsDir(projectId), `${this.validateCommitSha(commitSha)}.json`);
-  }
-  getProjectLockPath(projectId) { return path.join(this.getProjectMetadataDir(projectId), '.project.lock'); }
-  getRegistryLockPath() { return path.join(this.dataDir, 'runtime', 'locks', 'projects.lock'); }
-
-  getIndexPath() { return path.join(this.dataDir, 'index', 'knowledge.lancedb'); }
-  getCachePath(...segments) { return path.join(this.dataDir, 'cache', ...segments); }
-  getRuntimePath(...segments) { return path.join(this.dataDir, 'runtime', ...segments); }
-  getRecoveryPath(...segments) { return path.join(this.dataDir, 'recovery', ...segments); }
-
-  getLogPath(scope = 'app', projectId = '') {
-    if (scope === 'system') return path.join(this.dataDir, 'logs', 'system');
-    // app/hooks are read-only compatibility locations for pre-v13 logs.
-    if (scope === 'app') return path.join(this.dataDir, 'logs', 'app');
-    if (scope === 'hooks') return path.join(this.dataDir, 'logs', 'hooks');
-    if (scope === 'project' || scope === 'projects') {
-      return path.join(this.dataDir, 'logs', 'projects', validateProjectId(projectId));
-    }
-    throw new DomainError('INVALID_ARGUMENT', `Unknown log scope: ${scope}.`);
-  }
-
-  getKnowledgeRootPath(settings) {
-    const root = settings && settings.knowledge && settings.knowledge.rootPath;
-    if (!root || typeof root !== 'string') {
-      throw new DomainError('INVALID_ARGUMENT', 'Knowledge root is not configured.', { status: 409 });
-    }
-    return path.resolve(root);
-  }
-
-  resolveNewProjectKnowledgePath(storageName, settings) {
-    const safe = String(storageName || '').trim();
-    if (!safe || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(safe)) {
-      throw new DomainError('INVALID_ARGUMENT', 'Invalid storageName.');
-    }
-    return path.join(this.getKnowledgeRootPath(settings), safe);
-  }
-
-  getProjectKnowledgePath(config) {
-    if (!config || typeof config.knowledgePath !== 'string' || !config.knowledgePath.trim()) {
-      throw new DomainError('DATA_CORRUPT', 'Project knowledgePath is missing.', { status: 500 });
-    }
-    return path.resolve(config.knowledgePath);
-  }
-
-  normalizeForComparison(value) {
-    if (!value || typeof value !== 'string') return '';
-    const normalized = stripTrailingSeparators(path.resolve(value));
-    return this.platform === 'win32' ? normalized.toLowerCase() : normalized;
-  }
-
-  pathsEqual(left, right) {
-    const a = this.normalizeForComparison(left);
-    const b = this.normalizeForComparison(right);
-    return Boolean(a && b && a === b);
-  }
-
-  isPathInside(root, target, options = {}) {
-    if (!root || !target) return false;
-    const resolve = options.realpath === false ? path.resolve : value => this.realpathWithMissingLeaf(value);
-    let rootPath;
-    let targetPath;
-    try {
-      rootPath = resolve(root);
-      targetPath = resolve(target);
-    } catch {
-      return false;
-    }
-    const rel = path.relative(rootPath, targetPath);
-    if (rel === '') return options.allowRoot !== false;
-    return !rel.startsWith('..') && !path.isAbsolute(rel);
-  }
-
-  realpathWithMissingLeaf(value) {
-    let current = path.resolve(value);
-    const suffix = [];
-    while (!fs.existsSync(current)) {
-      const parent = path.dirname(current);
-      if (parent === current) break;
-      suffix.unshift(path.basename(current));
-      current = parent;
-    }
-    const real = fs.realpathSync.native ? fs.realpathSync.native(current) : fs.realpathSync(current);
-    return path.join(real, ...suffix);
-  }
-
-  validateKnowledgeRoot(rootPath) {
-    const absolute = path.resolve(String(rootPath || '').trim());
-    if (!rootPath) throw new DomainError('INVALID_ARGUMENT', 'Knowledge root is required.');
-    let created = false;
-    if (!fs.existsSync(absolute)) {
-      fs.mkdirSync(absolute, { recursive: true });
-      created = true;
-    }
-    if (!fs.statSync(absolute).isDirectory()) {
-      throw new DomainError('INVALID_ARGUMENT', 'Knowledge root must be a directory.');
-    }
-    const probe = path.join(absolute, `.project-knowledge-write-probe-${process.pid}-${crypto.randomBytes(6).toString('hex')}`);
-    try {
-      const fd = fs.openSync(probe, 'wx', 0o600);
-      fs.fsyncSync(fd);
-      fs.closeSync(fd);
-      fs.unlinkSync(probe);
-    } catch (error) {
-      try { if (fs.existsSync(probe)) fs.unlinkSync(probe); } catch {
-        // Preserve the writability error; a uniquely named failed probe is never runtime data.
-      }
-      throw new DomainError('INVALID_ARGUMENT', 'Knowledge root is not writable.', { status: 400, cause: error });
-    }
-    return { ok: true, rootPath: absolute, created };
-  }
-}
-
-function createStorageLayout(options) {
-  return new StorageLayout(options);
-}
-
-module.exports = { StorageLayout, createStorageLayout };
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const dataDirModule = require('./data-dir');
+const { DomainError, validateProjectId } = require('./contracts');
+
+function stripTrailingSeparators(value) {
+  const parsed = path.parse(value);
+  let result = value;
+  while (result.length > parsed.root.length && /[\\/]$/.test(result)) result = result.slice(0, -1);
+  return result;
+}
+
+class StorageLayout {
+  constructor(options = {}) {
+    this.dataDir = path.resolve(options.dataDir || dataDirModule.getDataDir());
+    this.platform = options.platform || process.platform;
+  }
+
+  getDataDir() { return this.dataDir; }
+  getSettingsPath() { return path.join(this.dataDir, 'settings.json'); }
+  getProjectRegistryPath() { return path.join(this.dataDir, 'projects.json'); }
+  getMigrationStatePath() { return path.join(this.dataDir, 'runtime', 'migration-state.json'); }
+  getMigrationCompletionPath() { return path.join(this.dataDir, 'runtime', 'layout-v2.completed.json'); }
+
+  getProjectMetadataDir(projectId) {
+    return path.join(this.dataDir, 'projects', validateProjectId(projectId));
+  }
+
+  getProjectConfigPath(projectId) { return path.join(this.getProjectMetadataDir(projectId), 'config.json'); }
+  getProjectStatePath(projectId) { return path.join(this.getProjectMetadataDir(projectId), 'state.json'); }
+  getProjectRequirementsPath(projectId) { return path.join(this.getProjectMetadataDir(projectId), 'requirements.jsonl'); }
+  getProjectConversationEventsPath(projectId) { return path.join(this.getProjectMetadataDir(projectId), 'conversation-events.jsonl'); }
+  getProjectCommitBoundariesDir(projectId) { return path.join(this.getProjectMetadataDir(projectId), 'commit-boundaries'); }
+  getProjectCommitConversationsDir(projectId) { return path.join(this.getProjectMetadataDir(projectId), 'commit-conversations'); }
+  validateCommitSha(commitSha) {
+    const value = String(commitSha || '').trim().toLowerCase();
+    if (!/^[a-f0-9]{7,64}$/.test(value)) throw new DomainError('INVALID_ARGUMENT', 'Invalid commit SHA.');
+    return value;
+  }
+  getProjectCommitBoundaryPath(projectId, commitSha) {
+    return path.join(this.getProjectCommitBoundariesDir(projectId), `${this.validateCommitSha(commitSha)}.json`);
+  }
+  getProjectCommitConversationPath(projectId, commitSha) {
+    return path.join(this.getProjectCommitConversationsDir(projectId), `${this.validateCommitSha(commitSha)}.json`);
+  }
+  getProjectLockPath(projectId) { return path.join(this.getProjectMetadataDir(projectId), '.project.lock'); }
+  getRegistryLockPath() { return path.join(this.dataDir, 'runtime', 'locks', 'projects.lock'); }
+
+  getIndexPath() { return path.join(this.dataDir, 'index', 'knowledge.lancedb'); }
+  getCachePath(...segments) { return path.join(this.dataDir, 'cache', ...segments); }
+  getRuntimePath(...segments) { return path.join(this.dataDir, 'runtime', ...segments); }
+  getRecoveryPath(...segments) { return path.join(this.dataDir, 'recovery', ...segments); }
+
+  getLogPath(scope = 'app', projectId = '') {
+    if (scope === 'system') return path.join(this.dataDir, 'logs', 'system');
+    // app/hooks are read-only compatibility locations for pre-v13 logs.
+    if (scope === 'app') return path.join(this.dataDir, 'logs', 'app');
+    if (scope === 'hooks') return path.join(this.dataDir, 'logs', 'hooks');
+    if (scope === 'project' || scope === 'projects') {
+      return path.join(this.dataDir, 'logs', 'projects', validateProjectId(projectId));
+    }
+    throw new DomainError('INVALID_ARGUMENT', `Unknown log scope: ${scope}.`);
+  }
+
+  getKnowledgeRootPath(settings) {
+    const root = settings && settings.knowledge && settings.knowledge.rootPath;
+    if (!root || typeof root !== 'string') {
+      throw new DomainError('INVALID_ARGUMENT', 'Knowledge root is not configured.', { status: 409 });
+    }
+    return path.resolve(root);
+  }
+
+  resolveNewProjectKnowledgePath(storageName, settings) {
+    const safe = String(storageName || '').trim();
+    if (!safe || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(safe)) {
+      throw new DomainError('INVALID_ARGUMENT', 'Invalid storageName.');
+    }
+    return path.join(this.getKnowledgeRootPath(settings), safe);
+  }
+
+  getProjectKnowledgePath(config) {
+    if (!config || typeof config.knowledgePath !== 'string' || !config.knowledgePath.trim()) {
+      throw new DomainError('DATA_CORRUPT', 'Project knowledgePath is missing.', { status: 500 });
+    }
+    return path.resolve(config.knowledgePath);
+  }
+
+  normalizeForComparison(value) {
+    if (!value || typeof value !== 'string') return '';
+    const normalized = stripTrailingSeparators(path.resolve(value));
+    return this.platform === 'win32' ? normalized.toLowerCase() : normalized;
+  }
+
+  pathsEqual(left, right) {
+    const a = this.normalizeForComparison(left);
+    const b = this.normalizeForComparison(right);
+    return Boolean(a && b && a === b);
+  }
+
+  isPathInside(root, target, options = {}) {
+    if (!root || !target) return false;
+    const resolve = options.realpath === false ? path.resolve : value => this.realpathWithMissingLeaf(value);
+    let rootPath;
+    let targetPath;
+    try {
+      rootPath = resolve(root);
+      targetPath = resolve(target);
+    } catch {
+      return false;
+    }
+    const rel = path.relative(rootPath, targetPath);
+    if (rel === '') return options.allowRoot !== false;
+    return !rel.startsWith('..') && !path.isAbsolute(rel);
+  }
+
+  realpathWithMissingLeaf(value) {
+    let current = path.resolve(value);
+    const suffix = [];
+    while (!fs.existsSync(current)) {
+      const parent = path.dirname(current);
+      if (parent === current) break;
+      suffix.unshift(path.basename(current));
+      current = parent;
+    }
+    const real = fs.realpathSync.native ? fs.realpathSync.native(current) : fs.realpathSync(current);
+    return path.join(real, ...suffix);
+  }
+
+  validateKnowledgeRoot(rootPath) {
+    const absolute = path.resolve(String(rootPath || '').trim());
+    if (!rootPath) throw new DomainError('INVALID_ARGUMENT', 'Knowledge root is required.');
+    let created = false;
+    if (!fs.existsSync(absolute)) {
+      fs.mkdirSync(absolute, { recursive: true });
+      created = true;
+    }
+    if (!fs.statSync(absolute).isDirectory()) {
+      throw new DomainError('INVALID_ARGUMENT', 'Knowledge root must be a directory.');
+    }
+    const probe = path.join(absolute, `.project-knowledge-write-probe-${process.pid}-${crypto.randomBytes(6).toString('hex')}`);
+    try {
+      const fd = fs.openSync(probe, 'wx', 0o600);
+      fs.fsyncSync(fd);
+      fs.closeSync(fd);
+      fs.unlinkSync(probe);
+    } catch (error) {
+      try { if (fs.existsSync(probe)) fs.unlinkSync(probe); } catch {
+        // Preserve the writability error; a uniquely named failed probe is never runtime data.
+      }
+      throw new DomainError('INVALID_ARGUMENT', 'Knowledge root is not writable.', { status: 400, cause: error });
+    }
+    return { ok: true, rootPath: absolute, created };
+  }
+}
+
+function createStorageLayout(options) {
+  return new StorageLayout(options);
+}
+
+module.exports = { StorageLayout, createStorageLayout };