@sanqianx/project-knowledge 5.0.24 → 5.0.25

package/_site/lib/index-builder.js

@@ -1,157 +1,157 @@
-const fs = require('fs');
-const path = require('path');
-
-const MAX_INDEX_ITEMS = 40;
-const MAX_MODULE_ITEMS = 80;
-const MAX_TAGS = 4;
-const MAX_SOURCE_PATHS = 3;
-const MAX_LOOKUPS = 4;
-const MAX_CELL_CHARS = 120;
-const GENERATED_NOTICE = '<!-- Generated by project-knowledge. Do not edit manually. -->';
-
-function parseFrontmatter(text) {
-  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/.exec(String(text || ''));
-  if (!match) return {};
-  const meta = {};
-  for (const line of match[1].split(/\r?\n/)) {
-    const m = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line.trim());
-    if (!m) continue;
-    let value = m[2].trim();
-    if (/^\[.*\]$/.test(value)) {
-      value = value.slice(1, -1).split(',').map(s => s.trim()).filter(Boolean);
-    }
-    meta[m[1]] = value;
-  }
-  return meta;
-}
-
-function listMarkdown(dir) {
-  if (!fs.existsSync(dir)) return [];
-  return fs.readdirSync(dir, { withFileTypes: true })
-    .filter(entry => entry.isFile() && entry.name.endsWith('.md') && entry.name !== '00-index.md')
-    .map(entry => {
-      const rel = entry.name;
-      const full = path.join(dir, entry.name);
-      const text = fs.readFileSync(full, 'utf-8');
-      const meta = parseFrontmatter(text);
-      const title = meta.title || text.match(/^#\s+(.+)$/m)?.[1] || entry.name.replace(/\.md$/, '');
-      return { rel, full, meta, title, updatedAt: meta.updatedAt || meta.period || '' };
-    });
-}
-
-function metaList(value) {
-  if (Array.isArray(value)) return value.filter(Boolean);
-  if (!value) return [];
-  return String(value).split(',').map(s => s.trim()).filter(Boolean);
-}
-
-function compactList(value, limit) {
-  const items = metaList(value);
-  if (items.length <= limit) return items.join(', ');
-  return `${items.slice(0, limit).join(', ')} (+${items.length - limit})`;
-}
-
-function cell(value, maxChars = MAX_CELL_CHARS) {
-  const text = Array.isArray(value) ? value.join(', ') : String(value || '');
-  const clean = text.replace(/\r?\n/g, ' ').replace(/\|/g, '\\|').trim();
-  if (!clean) return '-';
-  return clean.length > maxChars ? `${clean.slice(0, Math.max(1, maxChars - 1)).trimEnd()}…` : clean;
-}
-
-function indexSummary(total, shown) {
-  return shown < total
-    ? `Items: ${total} (showing ${shown}; use knowledge search or file search for older entries)`
-    : `Items: ${total}`;
-}
-
-function markdownLink(title, rel) {
-  const label = cell(title, 80).replace(/\[/g, '\\[').replace(/\]/g, '\\]');
-  const target = encodeURI(String(rel || '')).replace(/\(/g, '%28').replace(/\)/g, '%29');
-  return `[${label}](./${target})`;
-}
-
-function renderModuleIndex(kbPath) {
-  const dir = path.join(kbPath, 'modules');
-  const items = listMarkdown(dir).sort((a, b) => a.title.localeCompare(b.title));
-  const visible = items.slice(0, MAX_MODULE_ITEMS);
-  const lines = [
-    GENERATED_NOTICE,
-    '',
-    '# Modules Index',
-    '',
-    indexSummary(items.length, visible.length),
-    '',
-    '| Module | Tags | Source Paths | Routes / Symbols | Updated |',
-    '|---|---|---|---|---|',
-  ];
-  for (const item of visible) {
-    const tagsText = compactList(item.meta.tags, MAX_TAGS);
-    const sourcePaths = compactList(item.meta.sourcePaths, MAX_SOURCE_PATHS);
-    const routes = metaList(item.meta.routes);
-    const symbols = metaList(item.meta.symbols);
-    const lookup = compactList([...routes, ...symbols], MAX_LOOKUPS);
-    lines.push(`| ${markdownLink(item.title, item.rel)} | ${cell(tagsText)} | ${cell(sourcePaths)} | ${cell(lookup)} | ${cell(item.updatedAt)} |`);
-  }
-  if (!items.length) lines.push('| No modules yet | - | - | - | - |');
-  return { path: 'modules/00-index.md', count: items.length, content: lines.join('\n') + '\n' };
-}
-
-function writeModuleIndex(kbPath) {
-  const rendered = renderModuleIndex(kbPath);
-  const dest = path.join(kbPath, rendered.path);
-  fs.mkdirSync(path.dirname(dest), { recursive: true });
-  fs.writeFileSync(dest, rendered.content, 'utf-8');
-  return { path: rendered.path, count: rendered.count };
-}
-
-function renderChangesIndex(kbPath) {
-  const dir = path.join(kbPath, 'changes');
-  const items = listMarkdown(dir).sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)) || a.title.localeCompare(b.title));
-  const visible = items.slice(0, MAX_INDEX_ITEMS);
-  const lines = [
-    GENERATED_NOTICE,
-    '',
-    '# Changes Index',
-    '',
-    indexSummary(items.length, visible.length),
-    '',
-    '| Change | Tags | Affected Modules | Period / Updated | Intent |',
-    '|---|---|---|---|---|',
-  ];
-  for (const item of visible) {
-    const tagsText = compactList(item.meta.tags, MAX_TAGS);
-    const affected = compactList(item.meta.affectedModules, MAX_SOURCE_PATHS);
-    const intent = item.meta.developmentIntent || item.meta.intent || '';
-    lines.push(`| ${markdownLink(item.title, item.rel)} | ${cell(tagsText)} | ${cell(affected)} | ${cell(item.updatedAt)} | ${cell(intent)} |`);
-  }
-  if (!items.length) lines.push('| No changes yet | - | - | - | - |');
-  return { path: 'changes/00-index.md', count: items.length, content: lines.join('\n') + '\n' };
-}
-
-function writeChangesIndex(kbPath) {
-  const rendered = renderChangesIndex(kbPath);
-  const dest = path.join(kbPath, rendered.path);
-  fs.mkdirSync(path.dirname(dest), { recursive: true });
-  fs.writeFileSync(dest, rendered.content, 'utf-8');
-  return { path: rendered.path, count: rendered.count };
-}
-
-function regenerateIndexes(kbPath) {
-  return {
-    modules: writeModuleIndex(kbPath),
-    changes: writeChangesIndex(kbPath),
-  };
-}
-
-module.exports = {
-  parseFrontmatter,
-  compactList,
-  cell,
-  markdownLink,
-  GENERATED_NOTICE,
-  renderModuleIndex,
-  renderChangesIndex,
-  regenerateIndexes,
-  writeModuleIndex,
-  writeChangesIndex,
-};
+const fs = require('fs');
+const path = require('path');
+
+const MAX_INDEX_ITEMS = 40;
+const MAX_MODULE_ITEMS = 80;
+const MAX_TAGS = 4;
+const MAX_SOURCE_PATHS = 3;
+const MAX_LOOKUPS = 4;
+const MAX_CELL_CHARS = 120;
+const GENERATED_NOTICE = '<!-- Generated by project-knowledge. Do not edit manually. -->';
+
+function parseFrontmatter(text) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/.exec(String(text || ''));
+  if (!match) return {};
+  const meta = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const m = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line.trim());
+    if (!m) continue;
+    let value = m[2].trim();
+    if (/^\[.*\]$/.test(value)) {
+      value = value.slice(1, -1).split(',').map(s => s.trim()).filter(Boolean);
+    }
+    meta[m[1]] = value;
+  }
+  return meta;
+}
+
+function listMarkdown(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true })
+    .filter(entry => entry.isFile() && entry.name.endsWith('.md') && entry.name !== '00-index.md')
+    .map(entry => {
+      const rel = entry.name;
+      const full = path.join(dir, entry.name);
+      const text = fs.readFileSync(full, 'utf-8');
+      const meta = parseFrontmatter(text);
+      const title = meta.title || text.match(/^#\s+(.+)$/m)?.[1] || entry.name.replace(/\.md$/, '');
+      return { rel, full, meta, title, updatedAt: meta.updatedAt || meta.period || '' };
+    });
+}
+
+function metaList(value) {
+  if (Array.isArray(value)) return value.filter(Boolean);
+  if (!value) return [];
+  return String(value).split(',').map(s => s.trim()).filter(Boolean);
+}
+
+function compactList(value, limit) {
+  const items = metaList(value);
+  if (items.length <= limit) return items.join(', ');
+  return `${items.slice(0, limit).join(', ')} (+${items.length - limit})`;
+}
+
+function cell(value, maxChars = MAX_CELL_CHARS) {
+  const text = Array.isArray(value) ? value.join(', ') : String(value || '');
+  const clean = text.replace(/\r?\n/g, ' ').replace(/\|/g, '\\|').trim();
+  if (!clean) return '-';
+  return clean.length > maxChars ? `${clean.slice(0, Math.max(1, maxChars - 1)).trimEnd()}…` : clean;
+}
+
+function indexSummary(total, shown) {
+  return shown < total
+    ? `Items: ${total} (showing ${shown}; use knowledge search or file search for older entries)`
+    : `Items: ${total}`;
+}
+
+function markdownLink(title, rel) {
+  const label = cell(title, 80).replace(/\[/g, '\\[').replace(/\]/g, '\\]');
+  const target = encodeURI(String(rel || '')).replace(/\(/g, '%28').replace(/\)/g, '%29');
+  return `[${label}](./${target})`;
+}
+
+function renderModuleIndex(kbPath) {
+  const dir = path.join(kbPath, 'modules');
+  const items = listMarkdown(dir).sort((a, b) => a.title.localeCompare(b.title));
+  const visible = items.slice(0, MAX_MODULE_ITEMS);
+  const lines = [
+    GENERATED_NOTICE,
+    '',
+    '# Modules Index',
+    '',
+    indexSummary(items.length, visible.length),
+    '',
+    '| Module | Tags | Source Paths | Routes / Symbols | Updated |',
+    '|---|---|---|---|---|',
+  ];
+  for (const item of visible) {
+    const tagsText = compactList(item.meta.tags, MAX_TAGS);
+    const sourcePaths = compactList(item.meta.sourcePaths, MAX_SOURCE_PATHS);
+    const routes = metaList(item.meta.routes);
+    const symbols = metaList(item.meta.symbols);
+    const lookup = compactList([...routes, ...symbols], MAX_LOOKUPS);
+    lines.push(`| ${markdownLink(item.title, item.rel)} | ${cell(tagsText)} | ${cell(sourcePaths)} | ${cell(lookup)} | ${cell(item.updatedAt)} |`);
+  }
+  if (!items.length) lines.push('| No modules yet | - | - | - | - |');
+  return { path: 'modules/00-index.md', count: items.length, content: lines.join('\n') + '\n' };
+}
+
+function writeModuleIndex(kbPath) {
+  const rendered = renderModuleIndex(kbPath);
+  const dest = path.join(kbPath, rendered.path);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(dest, rendered.content, 'utf-8');
+  return { path: rendered.path, count: rendered.count };
+}
+
+function renderChangesIndex(kbPath) {
+  const dir = path.join(kbPath, 'changes');
+  const items = listMarkdown(dir).sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)) || a.title.localeCompare(b.title));
+  const visible = items.slice(0, MAX_INDEX_ITEMS);
+  const lines = [
+    GENERATED_NOTICE,
+    '',
+    '# Changes Index',
+    '',
+    indexSummary(items.length, visible.length),
+    '',
+    '| Change | Tags | Affected Modules | Period / Updated | Intent |',
+    '|---|---|---|---|---|',
+  ];
+  for (const item of visible) {
+    const tagsText = compactList(item.meta.tags, MAX_TAGS);
+    const affected = compactList(item.meta.affectedModules, MAX_SOURCE_PATHS);
+    const intent = item.meta.developmentIntent || item.meta.intent || '';
+    lines.push(`| ${markdownLink(item.title, item.rel)} | ${cell(tagsText)} | ${cell(affected)} | ${cell(item.updatedAt)} | ${cell(intent)} |`);
+  }
+  if (!items.length) lines.push('| No changes yet | - | - | - | - |');
+  return { path: 'changes/00-index.md', count: items.length, content: lines.join('\n') + '\n' };
+}
+
+function writeChangesIndex(kbPath) {
+  const rendered = renderChangesIndex(kbPath);
+  const dest = path.join(kbPath, rendered.path);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(dest, rendered.content, 'utf-8');
+  return { path: rendered.path, count: rendered.count };
+}
+
+function regenerateIndexes(kbPath) {
+  return {
+    modules: writeModuleIndex(kbPath),
+    changes: writeChangesIndex(kbPath),
+  };
+}
+
+module.exports = {
+  parseFrontmatter,
+  compactList,
+  cell,
+  markdownLink,
+  GENERATED_NOTICE,
+  renderModuleIndex,
+  renderChangesIndex,
+  regenerateIndexes,
+  writeModuleIndex,
+  writeChangesIndex,
+};

package/_site/lib/index-service.js

@@ -1,173 +1,173 @@
-const fs = require('fs');
-const path = require('path');
-const AtomicFile = require('./atomic-file');
-const { DomainError, createId, validateProjectId } = require('./contracts');
-const { StorageLayout } = require('./storage-layout');
-const { ProjectRegistryStore } = require('./project-registry-store');
-const { ProjectStore } = require('./project-store');
-const { CHUNKER_VERSION, listMarkdownFiles } = require('./markdown-knowledge-indexer');
-const { sha256 } = require('./knowledge-schema');
-
-let globalWriterTail = Promise.resolve();
-
-function buildSourceManifest(projectId, knowledgePath, generation, sourceCommit = '') {
-  const root = path.resolve(knowledgePath);
-  const entries = {};
-  for (const filePath of listMarkdownFiles(root)) {
-    const entryId = path.relative(root, filePath).replace(/\\/g, '/');
-    const markdown = fs.readFileSync(filePath, 'utf8');
-    entries[entryId] = {
-      entryId,
-      documentHash: sha256(`chunker:${CHUNKER_VERSION}\n${markdown}`),
-      sourceCommit: sourceCommit || '',
-    };
-  }
-  return {
-    schema: 'knowledge-index-source-manifest/v1',
-    projectId,
-    generation: Number(generation || 0),
-    sourceCommit: sourceCommit || null,
-    entries,
-    entryCount: Object.keys(entries).length,
-    updatedAt: new Date().toISOString(),
-  };
-}
-
-function enqueueGlobal(task) {
-  const run = globalWriterTail.catch(() => {}).then(task);
-  globalWriterTail = run.catch(() => {});
-  return run;
-}
-
-class IndexService {
-  constructor(options = {}) {
-    this.layout = options.layout || new StorageLayout(options);
-    this.registryStore = options.registryStore || new ProjectRegistryStore({ layout: this.layout });
-    this.projectStore = options.projectStore || new ProjectStore({ layout: this.layout });
-    this.adapter = options.adapter || null;
-    this.atomic = options.atomic || AtomicFile;
-    this.logger = options.logger || null;
-    this.pending = new Map();
-  }
-
-  async log(level, event, message, context) {
-    if (this.logger && typeof this.logger[level] === 'function') await this.logger[level](event, message, context);
-  }
-
-  enqueue(projectId) {
-    validateProjectId(projectId);
-    const existing = this.pending.get(projectId);
-    if (existing) {
-      existing.rerun = true;
-      return existing.promise;
-    }
-    const entry = { rerun: false, promise: null };
-    entry.promise = enqueueGlobal(() => this.processEntry(projectId, entry));
-    this.pending.set(projectId, entry);
-    entry.promise.finally(() => {
-      if (this.pending.get(projectId) === entry) this.pending.delete(projectId);
-    });
-    return entry.promise;
-  }
-
-  async processEntry(projectId, entry) {
-    let lastResult = { ok: true, skipped: true };
-    do {
-      entry.rerun = false;
-      lastResult = await this.processProject(projectId);
-      if (!lastResult.ok) return lastResult;
-      const state = this.projectStore.readState(projectId);
-      if (state.index.dirty) entry.rerun = true;
-    } while (entry.rerun);
-    return lastResult;
-  }
-
-  async processProject(projectId) {
-    const config = this.projectStore.readConfig(projectId);
-    const before = this.projectStore.readState(projectId);
-    if (!before.index.dirty) return { ok: true, skipped: true, projectId };
-    const generation = before.index.generation;
-    const operationId = createId('op');
-    try {
-      if (!this.adapter || typeof this.adapter.indexProject !== 'function') throw new DomainError('INVALID_ARGUMENT', 'Index adapter is unavailable.', { status: 503, retryable: true });
-      const result = await this.adapter.indexProject({
-        projectId,
-        config,
-        knowledgePath: config.knowledgePath,
-        indexPath: this.layout.getIndexPath(),
-        generation,
-        sinceCommit: before.index.sinceCommit,
-      });
-      const sourceManifest = buildSourceManifest(projectId, config.knowledgePath, generation, before.index.sinceCommit);
-      this.atomic.writeJsonAtomic(this.layout.getRuntimePath('index-sources', `${projectId}.json`), sourceManifest);
-      await this.projectStore.updateState(projectId, state => {
-        if (state.index.generation === generation) {
-          state.index.dirty = false;
-          state.index.sinceCommit = null;
-          state.index.lastError = null;
-          state.index.lastIndexedAt = new Date().toISOString();
-        }
-      });
-      await this.log('info', 'index.project_applied', 'Derived knowledge index updated.', { projectId, operationId, generation, phase: 'index.applied' });
-      return { ok: true, projectId, generation, result: result || null };
-    } catch (error) {
-      await this.projectStore.updateState(projectId, state => {
-        state.index.dirty = true;
-        state.index.lastError = {
-          code: error.code || 'INVALID_ARGUMENT',
-          message: String(error.message || 'Index update failed.'),
-          generation,
-          ts: new Date().toISOString(),
-        };
-      });
-      await this.log('error', 'index.project_failed', 'Derived index update failed; Markdown remains authoritative.', { projectId, operationId, generation, phase: 'index.queued', error });
-      return { ok: false, projectId, generation, error: { code: error.code || 'INVALID_ARGUMENT', message: error.message } };
-    }
-  }
-
-  retryDirtyProjects() {
-    return Promise.all(this.registryStore.listIds()
-      .filter(projectId => this.projectStore.readState(projectId).index.dirty)
-      .map(projectId => this.enqueue(projectId)));
-  }
-
-  async fullRebuild(options = {}) {
-    if (!this.adapter || typeof this.adapter.buildFull !== 'function' || typeof this.adapter.validateIndex !== 'function') {
-      throw new DomainError('INVALID_ARGUMENT', 'Index adapter does not support atomic full rebuild.', { status: 503 });
-    }
-    return enqueueGlobal(async () => {
-      const operationId = options.operationId || createId('op');
-      const target = this.layout.getIndexPath();
-      const parent = path.dirname(target);
-      const temp = path.join(parent, `.knowledge.rebuild.${operationId}`);
-      const backup = this.layout.getRecoveryPath('index', `${operationId}.previous`);
-      if (fs.existsSync(temp)) throw new DomainError('MIGRATION_TARGET_CONFLICT', 'Index rebuild staging already exists.', { status: 409 });
-      const projects = this.registryStore.listIds().map(projectId => ({ projectId, config: this.projectStore.readConfig(projectId) }));
-      try {
-        await this.adapter.buildFull({ targetPath: temp, projects });
-        const validation = await this.adapter.validateIndex(temp);
-        if (!validation || validation.ok !== true) throw new DomainError('DATA_CORRUPT', 'Rebuilt index validation failed.', { status: 500 });
-        fs.mkdirSync(path.dirname(backup), { recursive: true });
-        if (fs.existsSync(target)) fs.renameSync(target, backup);
-        try { fs.renameSync(temp, target); }
-        catch (error) {
-          if (fs.existsSync(backup) && !fs.existsSync(target)) fs.renameSync(backup, target);
-          throw error;
-        }
-        for (const { projectId, config } of projects) {
-          const state = this.projectStore.readState(projectId);
-          const sourceManifest = buildSourceManifest(projectId, config.knowledgePath, state.index.generation, state.index.sinceCommit);
-          this.atomic.writeJsonAtomic(this.layout.getRuntimePath('index-sources', `${projectId}.json`), sourceManifest);
-        }
-        return { ok: true, operationId, target, backup: fs.existsSync(backup) ? backup : null, validation };
-      } catch (error) {
-        if (fs.existsSync(temp)) fs.rmSync(temp, { recursive: true, force: true });
-        throw error;
-      }
-    });
-  }
-
-  static async flush() { await globalWriterTail.catch(() => {}); }
-}
-
-module.exports = { IndexService, enqueueGlobal, buildSourceManifest };
+const fs = require('fs');
+const path = require('path');
+const AtomicFile = require('./atomic-file');
+const { DomainError, createId, validateProjectId } = require('./contracts');
+const { StorageLayout } = require('./storage-layout');
+const { ProjectRegistryStore } = require('./project-registry-store');
+const { ProjectStore } = require('./project-store');
+const { CHUNKER_VERSION, listMarkdownFiles } = require('./markdown-knowledge-indexer');
+const { sha256 } = require('./knowledge-schema');
+
+let globalWriterTail = Promise.resolve();
+
+function buildSourceManifest(projectId, knowledgePath, generation, sourceCommit = '') {
+  const root = path.resolve(knowledgePath);
+  const entries = {};
+  for (const filePath of listMarkdownFiles(root)) {
+    const entryId = path.relative(root, filePath).replace(/\\/g, '/');
+    const markdown = fs.readFileSync(filePath, 'utf8');
+    entries[entryId] = {
+      entryId,
+      documentHash: sha256(`chunker:${CHUNKER_VERSION}\n${markdown}`),
+      sourceCommit: sourceCommit || '',
+    };
+  }
+  return {
+    schema: 'knowledge-index-source-manifest/v1',
+    projectId,
+    generation: Number(generation || 0),
+    sourceCommit: sourceCommit || null,
+    entries,
+    entryCount: Object.keys(entries).length,
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+function enqueueGlobal(task) {
+  const run = globalWriterTail.catch(() => {}).then(task);
+  globalWriterTail = run.catch(() => {});
+  return run;
+}
+
+class IndexService {
+  constructor(options = {}) {
+    this.layout = options.layout || new StorageLayout(options);
+    this.registryStore = options.registryStore || new ProjectRegistryStore({ layout: this.layout });
+    this.projectStore = options.projectStore || new ProjectStore({ layout: this.layout });
+    this.adapter = options.adapter || null;
+    this.atomic = options.atomic || AtomicFile;
+    this.logger = options.logger || null;
+    this.pending = new Map();
+  }
+
+  async log(level, event, message, context) {
+    if (this.logger && typeof this.logger[level] === 'function') await this.logger[level](event, message, context);
+  }
+
+  enqueue(projectId) {
+    validateProjectId(projectId);
+    const existing = this.pending.get(projectId);
+    if (existing) {
+      existing.rerun = true;
+      return existing.promise;
+    }
+    const entry = { rerun: false, promise: null };
+    entry.promise = enqueueGlobal(() => this.processEntry(projectId, entry));
+    this.pending.set(projectId, entry);
+    entry.promise.finally(() => {
+      if (this.pending.get(projectId) === entry) this.pending.delete(projectId);
+    });
+    return entry.promise;
+  }
+
+  async processEntry(projectId, entry) {
+    let lastResult = { ok: true, skipped: true };
+    do {
+      entry.rerun = false;
+      lastResult = await this.processProject(projectId);
+      if (!lastResult.ok) return lastResult;
+      const state = this.projectStore.readState(projectId);
+      if (state.index.dirty) entry.rerun = true;
+    } while (entry.rerun);
+    return lastResult;
+  }
+
+  async processProject(projectId) {
+    const config = this.projectStore.readConfig(projectId);
+    const before = this.projectStore.readState(projectId);
+    if (!before.index.dirty) return { ok: true, skipped: true, projectId };
+    const generation = before.index.generation;
+    const operationId = createId('op');
+    try {
+      if (!this.adapter || typeof this.adapter.indexProject !== 'function') throw new DomainError('INVALID_ARGUMENT', 'Index adapter is unavailable.', { status: 503, retryable: true });
+      const result = await this.adapter.indexProject({
+        projectId,
+        config,
+        knowledgePath: config.knowledgePath,
+        indexPath: this.layout.getIndexPath(),
+        generation,
+        sinceCommit: before.index.sinceCommit,
+      });
+      const sourceManifest = buildSourceManifest(projectId, config.knowledgePath, generation, before.index.sinceCommit);
+      this.atomic.writeJsonAtomic(this.layout.getRuntimePath('index-sources', `${projectId}.json`), sourceManifest);
+      await this.projectStore.updateState(projectId, state => {
+        if (state.index.generation === generation) {
+          state.index.dirty = false;
+          state.index.sinceCommit = null;
+          state.index.lastError = null;
+          state.index.lastIndexedAt = new Date().toISOString();
+        }
+      });
+      await this.log('info', 'index.project_applied', 'Derived knowledge index updated.', { projectId, operationId, generation, phase: 'index.applied' });
+      return { ok: true, projectId, generation, result: result || null };
+    } catch (error) {
+      await this.projectStore.updateState(projectId, state => {
+        state.index.dirty = true;
+        state.index.lastError = {
+          code: error.code || 'INVALID_ARGUMENT',
+          message: String(error.message || 'Index update failed.'),
+          generation,
+          ts: new Date().toISOString(),
+        };
+      });
+      await this.log('error', 'index.project_failed', 'Derived index update failed; Markdown remains authoritative.', { projectId, operationId, generation, phase: 'index.queued', error });
+      return { ok: false, projectId, generation, error: { code: error.code || 'INVALID_ARGUMENT', message: error.message } };
+    }
+  }
+
+  retryDirtyProjects() {
+    return Promise.all(this.registryStore.listIds()
+      .filter(projectId => this.projectStore.readState(projectId).index.dirty)
+      .map(projectId => this.enqueue(projectId)));
+  }
+
+  async fullRebuild(options = {}) {
+    if (!this.adapter || typeof this.adapter.buildFull !== 'function' || typeof this.adapter.validateIndex !== 'function') {
+      throw new DomainError('INVALID_ARGUMENT', 'Index adapter does not support atomic full rebuild.', { status: 503 });
+    }
+    return enqueueGlobal(async () => {
+      const operationId = options.operationId || createId('op');
+      const target = this.layout.getIndexPath();
+      const parent = path.dirname(target);
+      const temp = path.join(parent, `.knowledge.rebuild.${operationId}`);
+      const backup = this.layout.getRecoveryPath('index', `${operationId}.previous`);
+      if (fs.existsSync(temp)) throw new DomainError('MIGRATION_TARGET_CONFLICT', 'Index rebuild staging already exists.', { status: 409 });
+      const projects = this.registryStore.listIds().map(projectId => ({ projectId, config: this.projectStore.readConfig(projectId) }));
+      try {
+        await this.adapter.buildFull({ targetPath: temp, projects });
+        const validation = await this.adapter.validateIndex(temp);
+        if (!validation || validation.ok !== true) throw new DomainError('DATA_CORRUPT', 'Rebuilt index validation failed.', { status: 500 });
+        fs.mkdirSync(path.dirname(backup), { recursive: true });
+        if (fs.existsSync(target)) fs.renameSync(target, backup);
+        try { fs.renameSync(temp, target); }
+        catch (error) {
+          if (fs.existsSync(backup) && !fs.existsSync(target)) fs.renameSync(backup, target);
+          throw error;
+        }
+        for (const { projectId, config } of projects) {
+          const state = this.projectStore.readState(projectId);
+          const sourceManifest = buildSourceManifest(projectId, config.knowledgePath, state.index.generation, state.index.sinceCommit);
+          this.atomic.writeJsonAtomic(this.layout.getRuntimePath('index-sources', `${projectId}.json`), sourceManifest);
+        }
+        return { ok: true, operationId, target, backup: fs.existsSync(backup) ? backup : null, validation };
+      } catch (error) {
+        if (fs.existsSync(temp)) fs.rmSync(temp, { recursive: true, force: true });
+        throw error;
+      }
+    });
+  }
+
+  static async flush() { await globalWriterTail.catch(() => {}); }
+}
+
+module.exports = { IndexService, enqueueGlobal, buildSourceManifest };