@sanqianx/project-knowledge 5.0.18 → 5.0.20-rc.1

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

@@ -77,7 +77,7 @@ async function handlePostCommitEvent(event = {}, deps = {}) {
   return reconciler.processCommitEvent({ projectId, commitSha, branch: event.branch || '', operationId: deps.operationId || event.operationId || '' });
 }
 
-function cleanupOrphanedRuns(_projects, deps = {}) {
+function cleanupOrphanedRuns(_projects, deps = {}) {
   if (!deps.projectStore && !deps.registryStore && !deps.layout) {
     return { activeClaims: 0, recoveredFromFrozenClaims: 0, legacyStoreSkipped: true };
   }
@@ -86,56 +86,56 @@ function cleanupOrphanedRuns(_projects, deps = {}) {
   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,
-};
+  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 };

package/_site/lib/project-lifecycle-service.js

@@ -73,20 +73,20 @@ class ProjectLifecycleService {
     }
 
     // Check 2: git repository or can be initialized.
-    let repoInspection = null;
-    let plannedGitInit = false;
-    if (checks.path.ok) {
-      const inside = runGit(localPath, ['rev-parse', '--is-inside-work-tree'], { allowFailure: true });
-      const top = inside.ok ? runGit(localPath, ['rev-parse', '--show-toplevel'], { allowFailure: true }) : null;
-      // A folder merely nested below another repository is not itself an
-      // importable Git project. This matters on CI workspaces and prevents a
-      // selected plain folder from silently inheriting its parent's history.
-      const isRepoRoot = Boolean(top && top.ok && path.resolve(top.stdout) === path.resolve(localPath));
-      if (!inside.ok || !isRepoRoot) {
-        plannedGitInit = true;
-        checks.git = { ok: false, status: 'non-git', plannedInit: true, message: 'Directory is not a Git repository. Import will run `git init` before proceeding.' };
-      } else {
-        const head = runGit(localPath, ['rev-parse', '--verify', 'HEAD'], { allowFailure: true });
+    let repoInspection = null;
+    let plannedGitInit = false;
+    if (checks.path.ok) {
+      const inside = runGit(localPath, ['rev-parse', '--is-inside-work-tree'], { allowFailure: true });
+      const top = inside.ok ? runGit(localPath, ['rev-parse', '--show-toplevel'], { allowFailure: true }) : null;
+      // A folder merely nested below another repository is not itself an
+      // importable Git project. This matters on CI workspaces and prevents a
+      // selected plain folder from silently inheriting its parent's history.
+      const isRepoRoot = Boolean(top && top.ok && path.resolve(top.stdout) === path.resolve(localPath));
+      if (!inside.ok || !isRepoRoot) {
+        plannedGitInit = true;
+        checks.git = { ok: false, status: 'non-git', plannedInit: true, message: 'Directory is not a Git repository. Import will run `git init` before proceeding.' };
+      } else {
+        const head = runGit(localPath, ['rev-parse', '--verify', 'HEAD'], { allowFailure: true });
         const commonDir = runGit(localPath, ['rev-parse', '--git-common-dir']);
         const branch = runGit(localPath, ['branch', '--show-current'], { allowFailure: true });
         repoInspection = {

package/_site/lib/project-registry-store.js

@@ -1,129 +1,129 @@
-const { SCHEMAS, DomainError, validateProjectId } = require('./contracts');
-const AtomicFile = require('./atomic-file');
-const { StorageLayout } = require('./storage-layout');
-
-function emptyRegistry() {
-  return {
-    schema: SCHEMAS.projectRegistry,
-    schemaVersion: 2,
-    projectOrder: [],
-    projects: {},
-    revision: 0,
-    updatedAt: '',
-  };
-}
-
-function validateRegistry(registry) {
-  if (!registry || typeof registry !== 'object' || Array.isArray(registry)) {
-    throw new DomainError('DATA_CORRUPT', 'Project registry must be an object.', { status: 500 });
-  }
-  if (registry.schema !== SCHEMAS.projectRegistry || registry.schemaVersion !== 2) {
-    throw new DomainError('SCHEMA_UNSUPPORTED', 'Unsupported project registry schema.', { status: 409 });
-  }
-  if (!Array.isArray(registry.projectOrder) || !registry.projects || typeof registry.projects !== 'object') {
-    throw new DomainError('DATA_CORRUPT', 'Project registry index is invalid.', { status: 500 });
-  }
-  const ordered = new Set();
-  for (const projectId of registry.projectOrder) {
-    validateProjectId(projectId);
-    if (ordered.has(projectId) || !registry.projects[projectId]) {
-      throw new DomainError('DATA_CORRUPT', 'Project registry order is inconsistent.', { status: 500 });
-    }
-    ordered.add(projectId);
-  }
-  for (const projectId of Object.keys(registry.projects)) {
-    validateProjectId(projectId);
-    if (!ordered.has(projectId)) throw new DomainError('DATA_CORRUPT', 'Project registry contains an unordered project.', { status: 500 });
-  }
-  return registry;
-}
-
-class ProjectRegistryStore {
-  constructor(options = {}) {
-    this.layout = options.layout || new StorageLayout(options);
-    this.atomic = options.atomic || AtomicFile;
-    this.filePath = options.filePath || this.layout.getProjectRegistryPath();
-    this.lockPath = options.lockPath || this.layout.getRegistryLockPath();
-  }
-
-  read(options = {}) {
-    return this.atomic.readJsonStrict(this.filePath, {
-      allowMissing: options.allowMissing === true,
-      defaultValue: emptyRegistry(),
-      category: 'project-registry',
-      validate: validateRegistry,
-    });
-  }
-
-  async initialize() {
-    return this.atomic.withFileLock(this.lockPath, async () => {
-      let existing;
-      try { existing = this.read(); } catch (error) { if (!error || error.code !== 'ENOENT') throw error; }
-      if (existing) return existing;
-      const registry = emptyRegistry();
-      registry.updatedAt = new Date().toISOString();
-      this.atomic.writeJsonAtomic(this.filePath, registry);
-      return registry;
-    });
-  }
-
-  listIds() { return [...this.read({ allowMissing: true }).projectOrder]; }
-
-  readDisplaySnapshot(projectId) {
-    validateProjectId(projectId);
-    const registry = this.read({ allowMissing: true });
-    return registry.projects[projectId] || null;
-  }
-
-  async add(projectId, snapshot = {}) {
-    validateProjectId(projectId);
-    return this.atomic.withFileLock(this.lockPath, async () => {
-      const registry = this.read({ allowMissing: true });
-      if (registry.projects[projectId]) {
-        throw new DomainError('INVALID_ARGUMENT', 'Project is already registered.', { status: 409 });
-      }
-      registry.projects[projectId] = {
-        createdAt: String(snapshot.createdAt || new Date().toISOString()),
-        displayNameSnapshot: String(snapshot.displayNameSnapshot || snapshot.displayName || projectId),
-      };
-      registry.projectOrder.push(projectId);
-      registry.revision = Number(registry.revision || 0) + 1;
-      registry.updatedAt = new Date().toISOString();
-      validateRegistry(registry);
-      this.atomic.writeJsonAtomic(this.filePath, registry);
-      return registry.projects[projectId];
-    });
-  }
-
-  async remove(projectId) {
-    validateProjectId(projectId);
-    return this.atomic.withFileLock(this.lockPath, async () => {
-      const registry = this.read({ allowMissing: true });
-      if (!registry.projects[projectId]) return false;
-      delete registry.projects[projectId];
-      registry.projectOrder = registry.projectOrder.filter(id => id !== projectId);
-      registry.revision = Number(registry.revision || 0) + 1;
-      registry.updatedAt = new Date().toISOString();
-      validateRegistry(registry);
-      this.atomic.writeJsonAtomic(this.filePath, registry);
-      return true;
-    });
-  }
-
-  async reorder(projectIds) {
-    return this.atomic.withFileLock(this.lockPath, async () => {
-      const registry = this.read({ allowMissing: true });
-      const next = Array.isArray(projectIds) ? projectIds.map(validateProjectId) : [];
-      if (next.length !== registry.projectOrder.length || new Set(next).size !== next.length || next.some(id => !registry.projects[id])) {
-        throw new DomainError('INVALID_ARGUMENT', 'Reorder must contain every registered project exactly once.');
-      }
-      registry.projectOrder = next;
-      registry.revision = Number(registry.revision || 0) + 1;
-      registry.updatedAt = new Date().toISOString();
-      this.atomic.writeJsonAtomic(this.filePath, registry);
-      return [...next];
-    });
-  }
-}
-
-module.exports = { ProjectRegistryStore, emptyRegistry, validateRegistry };
+const { SCHEMAS, DomainError, validateProjectId } = require('./contracts');
+const AtomicFile = require('./atomic-file');
+const { StorageLayout } = require('./storage-layout');
+
+function emptyRegistry() {
+  return {
+    schema: SCHEMAS.projectRegistry,
+    schemaVersion: 2,
+    projectOrder: [],
+    projects: {},
+    revision: 0,
+    updatedAt: '',
+  };
+}
+
+function validateRegistry(registry) {
+  if (!registry || typeof registry !== 'object' || Array.isArray(registry)) {
+    throw new DomainError('DATA_CORRUPT', 'Project registry must be an object.', { status: 500 });
+  }
+  if (registry.schema !== SCHEMAS.projectRegistry || registry.schemaVersion !== 2) {
+    throw new DomainError('SCHEMA_UNSUPPORTED', 'Unsupported project registry schema.', { status: 409 });
+  }
+  if (!Array.isArray(registry.projectOrder) || !registry.projects || typeof registry.projects !== 'object') {
+    throw new DomainError('DATA_CORRUPT', 'Project registry index is invalid.', { status: 500 });
+  }
+  const ordered = new Set();
+  for (const projectId of registry.projectOrder) {
+    validateProjectId(projectId);
+    if (ordered.has(projectId) || !registry.projects[projectId]) {
+      throw new DomainError('DATA_CORRUPT', 'Project registry order is inconsistent.', { status: 500 });
+    }
+    ordered.add(projectId);
+  }
+  for (const projectId of Object.keys(registry.projects)) {
+    validateProjectId(projectId);
+    if (!ordered.has(projectId)) throw new DomainError('DATA_CORRUPT', 'Project registry contains an unordered project.', { status: 500 });
+  }
+  return registry;
+}
+
+class ProjectRegistryStore {
+  constructor(options = {}) {
+    this.layout = options.layout || new StorageLayout(options);
+    this.atomic = options.atomic || AtomicFile;
+    this.filePath = options.filePath || this.layout.getProjectRegistryPath();
+    this.lockPath = options.lockPath || this.layout.getRegistryLockPath();
+  }
+
+  read(options = {}) {
+    return this.atomic.readJsonStrict(this.filePath, {
+      allowMissing: options.allowMissing === true,
+      defaultValue: emptyRegistry(),
+      category: 'project-registry',
+      validate: validateRegistry,
+    });
+  }
+
+  async initialize() {
+    return this.atomic.withFileLock(this.lockPath, async () => {
+      let existing;
+      try { existing = this.read(); } catch (error) { if (!error || error.code !== 'ENOENT') throw error; }
+      if (existing) return existing;
+      const registry = emptyRegistry();
+      registry.updatedAt = new Date().toISOString();
+      this.atomic.writeJsonAtomic(this.filePath, registry);
+      return registry;
+    });
+  }
+
+  listIds() { return [...this.read({ allowMissing: true }).projectOrder]; }
+
+  readDisplaySnapshot(projectId) {
+    validateProjectId(projectId);
+    const registry = this.read({ allowMissing: true });
+    return registry.projects[projectId] || null;
+  }
+
+  async add(projectId, snapshot = {}) {
+    validateProjectId(projectId);
+    return this.atomic.withFileLock(this.lockPath, async () => {
+      const registry = this.read({ allowMissing: true });
+      if (registry.projects[projectId]) {
+        throw new DomainError('INVALID_ARGUMENT', 'Project is already registered.', { status: 409 });
+      }
+      registry.projects[projectId] = {
+        createdAt: String(snapshot.createdAt || new Date().toISOString()),
+        displayNameSnapshot: String(snapshot.displayNameSnapshot || snapshot.displayName || projectId),
+      };
+      registry.projectOrder.push(projectId);
+      registry.revision = Number(registry.revision || 0) + 1;
+      registry.updatedAt = new Date().toISOString();
+      validateRegistry(registry);
+      this.atomic.writeJsonAtomic(this.filePath, registry);
+      return registry.projects[projectId];
+    });
+  }
+
+  async remove(projectId) {
+    validateProjectId(projectId);
+    return this.atomic.withFileLock(this.lockPath, async () => {
+      const registry = this.read({ allowMissing: true });
+      if (!registry.projects[projectId]) return false;
+      delete registry.projects[projectId];
+      registry.projectOrder = registry.projectOrder.filter(id => id !== projectId);
+      registry.revision = Number(registry.revision || 0) + 1;
+      registry.updatedAt = new Date().toISOString();
+      validateRegistry(registry);
+      this.atomic.writeJsonAtomic(this.filePath, registry);
+      return true;
+    });
+  }
+
+  async reorder(projectIds) {
+    return this.atomic.withFileLock(this.lockPath, async () => {
+      const registry = this.read({ allowMissing: true });
+      const next = Array.isArray(projectIds) ? projectIds.map(validateProjectId) : [];
+      if (next.length !== registry.projectOrder.length || new Set(next).size !== next.length || next.some(id => !registry.projects[id])) {
+        throw new DomainError('INVALID_ARGUMENT', 'Reorder must contain every registered project exactly once.');
+      }
+      registry.projectOrder = next;
+      registry.revision = Number(registry.revision || 0) + 1;
+      registry.updatedAt = new Date().toISOString();
+      this.atomic.writeJsonAtomic(this.filePath, registry);
+      return [...next];
+    });
+  }
+}
+
+module.exports = { ProjectRegistryStore, emptyRegistry, validateRegistry };