@sanqianx/project-knowledge 4.7.0 → 5.0.0

package/_modules/knowledge-engine/src/runtime/atomic-file.js

@@ -0,0 +1,204 @@
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { DomainError } = require('./contracts');
+
+const DEFAULT_LOCK_TIMEOUT_MS = 10_000;
+const DEFAULT_STALE_LOCK_MS = 120_000;
+
+function delay(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error && error.code === 'EPERM';
+  }
+}
+
+function readLockOwner(lockPath) {
+  try { return JSON.parse(fs.readFileSync(lockPath, 'utf8')); } catch { return null; }
+}
+
+function canBreakStaleLock(lockPath, staleMs) {
+  let stat;
+  try { stat = fs.statSync(lockPath); } catch { return false; }
+  const owner = readLockOwner(lockPath);
+  // A complete owner record lets us recover immediately after a process
+  // crash. The age threshold is only needed for an incomplete/unreadable
+  // file that another process may still be creating.
+  if (owner && Number.isInteger(Number(owner.pid))) return !isProcessAlive(Number(owner.pid));
+  return (Date.now() - stat.mtimeMs) >= staleMs;
+}
+
+async function acquireFileLock(lockPath, options = {}) {
+  const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : DEFAULT_LOCK_TIMEOUT_MS;
+  const staleMs = Number.isFinite(options.staleMs) ? options.staleMs : DEFAULT_STALE_LOCK_MS;
+  const retryMs = Number.isFinite(options.retryMs) ? options.retryMs : 25;
+  const started = Date.now();
+  const nonce = crypto.randomBytes(12).toString('hex');
+  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+  while (true) {
+    try {
+      const fd = fs.openSync(lockPath, 'wx', 0o600);
+      const owner = { pid: process.pid, startedAt: new Date().toISOString(), nonce };
+      fs.writeFileSync(fd, `${JSON.stringify(owner)}\n`, 'utf8');
+      fs.fsyncSync(fd);
+      fs.closeSync(fd);
+      return async function release() {
+        const current = readLockOwner(lockPath);
+        if (!current || current.nonce !== nonce) return;
+        try { fs.unlinkSync(lockPath); } catch (error) { if (!error || error.code !== 'ENOENT') throw error; }
+      };
+    } catch (error) {
+      if (!error || error.code !== 'EEXIST') throw error;
+      if (canBreakStaleLock(lockPath, staleMs)) {
+        try { fs.unlinkSync(lockPath); continue; } catch (unlinkError) {
+          // A competing process may recover the same stale lock first; retry through the normal wait path.
+        }
+      }
+      if ((Date.now() - started) >= timeoutMs) {
+        throw new DomainError('PROJECT_BUSY', 'Timed out waiting for a file lock.', {
+          status: 409,
+          retryable: true,
+          details: { lockCategory: path.basename(lockPath) },
+        });
+      }
+      await delay(retryMs);
+    }
+  }
+}
+
+async function withFileLock(lockPath, fn, options = {}) {
+  const release = await acquireFileLock(lockPath, options);
+  try { return await fn(); } finally { await release(); }
+}
+
+function syncDirectoryBestEffort(directory) {
+  let fd;
+  try {
+    fd = fs.openSync(directory, 'r');
+    fs.fsyncSync(fd);
+  } catch {
+    // Directory fsync is unsupported on some filesystems; the file replace is already durable.
+  } finally {
+    if (fd != null) try { fs.closeSync(fd); } catch {
+      // Closing a best-effort directory descriptor cannot invalidate the completed file replace.
+    }
+  }
+}
+
+function replaceWithRetry(tempPath, targetPath, options = {}) {
+  const retries = Number.isInteger(options.renameRetries) ? options.renameRetries : 8;
+  const waitBuffer = new Int32Array(new SharedArrayBuffer(4));
+  let lastError;
+  for (let attempt = 0; attempt <= retries; attempt += 1) {
+    try {
+      fs.renameSync(tempPath, targetPath);
+      return;
+    } catch (error) {
+      lastError = error;
+      if (!error || !['EPERM', 'EACCES', 'EBUSY', 'EEXIST'].includes(error.code) || attempt === retries) break;
+      Atomics.wait(waitBuffer, 0, 0, Math.min(250, 10 * (2 ** attempt)));
+    }
+  }
+  throw lastError;
+}
+
+function writeFileAtomic(filePath, content, options = {}) {
+  const directory = path.dirname(filePath);
+  fs.mkdirSync(directory, { recursive: true });
+  const tempPath = path.join(directory, `.${path.basename(filePath)}.${process.pid}.${Date.now()}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+  let fd;
+  try {
+    fd = fs.openSync(tempPath, 'wx', options.mode || 0o600);
+    fs.writeFileSync(fd, content, options.encoding || 'utf8');
+    fs.fsyncSync(fd);
+    fs.closeSync(fd);
+    fd = null;
+    if (typeof options.beforeRename === 'function') options.beforeRename(tempPath, filePath);
+    replaceWithRetry(tempPath, filePath, options);
+    syncDirectoryBestEffort(directory);
+    return { path: filePath };
+  } catch (error) {
+    if (fd != null) try { fs.closeSync(fd); } catch {
+      // Preserve the original write error.
+    }
+    try { if (fs.existsSync(tempPath)) fs.unlinkSync(tempPath); } catch {
+      // Preserve the original write error; stale temp files are never treated as live data.
+    }
+    throw error;
+  }
+}
+
+function writeJsonAtomic(filePath, value, options = {}) {
+  return writeFileAtomic(filePath, `${JSON.stringify(value, null, 2)}\n`, options);
+}
+
+function readJsonStrict(filePath, options = {}) {
+  let raw;
+  try { raw = fs.readFileSync(filePath, 'utf8'); }
+  catch (error) {
+    if (error && error.code === 'ENOENT' && options.allowMissing) return options.defaultValue;
+    throw error;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof options.validate === 'function') options.validate(parsed);
+    return parsed;
+  } catch (error) {
+    if (error instanceof DomainError) throw error;
+    throw new DomainError('DATA_CORRUPT', 'A JSON data file is corrupt.', {
+      status: 500,
+      cause: error,
+      details: { category: options.category || 'json' },
+    });
+  }
+}
+
+async function appendJsonlLocked(filePath, value, options = {}) {
+  const lockPath = options.lockPath || `${filePath}.lock`;
+  return withFileLock(lockPath, async () => {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const fd = fs.openSync(filePath, 'a', options.mode || 0o600);
+    try {
+      fs.writeFileSync(fd, `${JSON.stringify(value)}\n`, 'utf8');
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    return value;
+  }, options);
+}
+
+function cleanupStaleTemps(directory, options = {}) {
+  if (!fs.existsSync(directory)) return [];
+  const olderThanMs = Number.isFinite(options.olderThanMs) ? options.olderThanMs : 24 * 60 * 60 * 1000;
+  const now = Date.now();
+  const removed = [];
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    if (!entry.isFile() || !/^\..+\.\d+\.\d+\.[a-f0-9]+\.tmp$/i.test(entry.name)) continue;
+    const absolute = path.join(directory, entry.name);
+    const stat = fs.statSync(absolute);
+    if ((now - stat.mtimeMs) < olderThanMs) continue;
+    fs.unlinkSync(absolute);
+    removed.push(absolute);
+  }
+  return removed;
+}
+
+module.exports = {
+  DEFAULT_LOCK_TIMEOUT_MS,
+  DEFAULT_STALE_LOCK_MS,
+  acquireFileLock,
+  withFileLock,
+  writeFileAtomic,
+  writeJsonAtomic,
+  readJsonStrict,
+  appendJsonlLocked,
+  cleanupStaleTemps,
+};

package/_modules/knowledge-engine/src/runtime/automation-config.js

@@ -0,0 +1,140 @@
+const path = require('path');
+
+const PERMISSION_MODES = new Set(['plan', 'default', 'acceptEdits', 'auto', 'bypassPermissions']);
+const PROMPT_TEMPLATE_VERSION = 2;
+
+const DEFAULT_COMMIT_PROMPT_TEMPLATE = `你正在根据一个 Git Commit 的冻结证据维护项目知识库。
+
+用户需求：
+{{userRequirement}}
+
+Commit 信息：
+{{commitMetadata}}
+
+Commit 实际变更文件：
+{{actualChanges}}
+
+Commit 实际 Patch：
+{{actualPatch}}
+
+现有相关知识：
+{{existingKnowledge}}
+
+请完成以下判断，并只输出符合 staging manifest 合同的知识变更：
+1. 比较用户需求与实际实现是否一致；没有可靠需求时不得猜测业务目的。
+2. 只记录 Commit、Patch 和现有知识能够证明的事实。
+3. 明确需要新增、更新或删除哪些知识；删除必须有实际变更证据。
+4. 不得修改源码、最终知识目录、其他项目或派生索引。
+5. Patch 使用 chunk evidence 时，必须从只读 manifest 按序读取所需 chunk；不得从源码工作树补读或猜测。`;
+
+const READ_TOOLS = ['Read'];
+const WRITE_TOOLS = ['Edit', 'Write', 'MultiEdit'];
+
+function normalizePermissionMode(value) {
+  return PERMISSION_MODES.has(value) ? value : 'default';
+}
+
+function normalizeAutomationConfig(input) {
+  const source = input && typeof input === 'object' ? input : {};
+  const explicit = typeof source.commitPromptTemplate === 'string' && source.commitPromptTemplate.trim();
+  const legacy = typeof source.hookPromptTemplate === 'string' && source.hookPromptTemplate.trim();
+  return {
+    enabled: source.enabled !== false,
+    commitPromptTemplate: explicit || legacy || DEFAULT_COMMIT_PROMPT_TEMPLATE,
+    promptTemplateVersion: PROMPT_TEMPLATE_VERSION,
+    legacyPromptOverride: !explicit && Boolean(legacy),
+  };
+}
+
+function normalizeClaudeWorkbenchConfig(input) {
+  const source = input && typeof input === 'object' ? input : {};
+  return { permissionMode: normalizePermissionMode(source.permissionMode) };
+}
+
+function renderTemplate(template, vars) {
+  const source = typeof template === 'string' && template.trim() ? template : DEFAULT_COMMIT_PROMPT_TEMPLATE;
+  const safeVars = vars && typeof vars === 'object' ? vars : {};
+  return source.replace(/\{\{\s*([A-Za-z][A-Za-z0-9_]*)\s*\}\}/g, (match, name) => {
+    if (!Object.prototype.hasOwnProperty.call(safeVars, name)) return match;
+    const value = safeVars[name];
+    return value == null ? '' : String(value);
+  });
+}
+
+function normalizePathForCompare(value) {
+  if (!value || typeof value !== 'string') return '';
+  const normalized = path.resolve(value).replace(/[\\/]+$/, '');
+  return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+
+function pathsReferToSameLocation(leftValue, rightValue) {
+  const left = normalizePathForCompare(leftValue);
+  const right = normalizePathForCompare(rightValue);
+  return Boolean(left && right && left === right);
+}
+
+function isInsidePath(root, target) {
+  if (!root || !target) return false;
+  const rootAbs = path.resolve(root);
+  const targetAbs = path.resolve(rootAbs, target);
+  const relative = path.relative(rootAbs, targetAbs);
+  return relative === '' || Boolean(relative && !relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function extractToolPaths(toolName, input) {
+  if (!input || typeof input !== 'object') return [];
+  const candidates = [];
+  for (const key of ['file_path', 'path', 'notebook_path']) {
+    if (typeof input[key] === 'string') candidates.push(input[key]);
+  }
+  if (toolName === 'MultiEdit' && typeof input.file_path === 'string') candidates.push(input.file_path);
+  return [...new Set(candidates)];
+}
+
+function buildAutomationToolPolicy(options = {}) {
+  const stagingPath = options.stagingPath || options.kbPath || '';
+  const evidenceRoot = options.evidenceRoot || '';
+  return {
+    kind: 'knowledge-staging',
+    stagingPath,
+    evidenceRoot,
+    readRoots: [evidenceRoot, stagingPath].filter(Boolean),
+    writeRoot: stagingPath,
+    allowedTools: [...READ_TOOLS, ...WRITE_TOOLS],
+    canWriteKb: false,
+    canWriteStaging: true,
+    allowReadOnlyBash: false,
+  };
+}
+
+function evaluateAutomationToolUse(policy, toolName, input) {
+  if (!policy || policy.kind !== 'knowledge-staging') return { behavior: 'ask', reason: 'no staging policy' };
+  if (!policy.allowedTools.includes(toolName)) return { behavior: 'deny', reason: `tool is not allowed: ${toolName}` };
+  const paths = extractToolPaths(toolName, input);
+  if (!paths.length) return { behavior: 'deny', reason: `${toolName} has no explicit file path` };
+  for (const filePath of paths) {
+    if (toolName === 'Read') {
+      if (!(policy.readRoots || []).some(root => isInsidePath(root, filePath))) {
+        return { behavior: 'deny', reason: `path outside read-only evidence/output roots: ${filePath}` };
+      }
+    } else if (!isInsidePath(policy.writeRoot || policy.stagingPath, filePath)) {
+      return { behavior: 'deny', reason: `path outside writable run output: ${filePath}` };
+    }
+  }
+  return { behavior: 'allow', reason: toolName === 'Read' ? 'path is inside an isolated read root' : 'path is inside the isolated writable output root' };
+}
+
+module.exports = {
+  PERMISSION_MODES,
+  PROMPT_TEMPLATE_VERSION,
+  DEFAULT_COMMIT_PROMPT_TEMPLATE,
+  normalizePermissionMode,
+  normalizeAutomationConfig,
+  normalizeClaudeWorkbenchConfig,
+  renderTemplate,
+  normalizePathForCompare,
+  pathsReferToSameLocation,
+  isInsidePath,
+  buildAutomationToolPolicy,
+  evaluateAutomationToolUse,
+};

package/_modules/knowledge-engine/src/runtime/commit-conversation-binder.js

@@ -0,0 +1,249 @@
+const fs = require('fs');
+const { DomainError, validateProjectId } = require('./contracts');
+const { ConversationStore, sha256 } = require('./conversation-store');
+const { readDevelopmentEvents } = require('./conversation-exclusions');
+
+function projectEvent(event) {
+  return {
+    eventId: event.eventId,
+    sequence: event.sequence,
+    content: event.content,
+    contentHash: event.contentHash,
+    capturedAt: event.capturedAt,
+  };
+}
+
+class CommitConversationBinder {
+  constructor(options = {}) {
+    this.layout = options.layout;
+    this.projectStore = options.projectStore;
+    this.conversationStore = options.conversationStore || new ConversationStore({
+      layout: this.layout,
+      projectStore: this.projectStore,
+      logger: options.logger,
+    });
+    this.logger = options.logger || null;
+  }
+
+  async log(level, event, message, context) {
+    if (this.logger && typeof this.logger[level] === 'function') await this.logger[level](event, message, context);
+  }
+
+  repoMatches(left, right) {
+    if (!left || !right) return false;
+    // workspaceId is the canonical primary key (I-06). commonDir/repoId are
+    // read-compat fallbacks for records stored before repo-identity/v1.
+    if (left.workspaceId && right.workspaceId) return String(left.workspaceId) === String(right.workspaceId);
+    if (left.commonDir && right.commonDir) return this.layout.pathsEqual(left.commonDir, right.commonDir);
+    if (left.repoId && right.repoId) return String(left.repoId) === String(right.repoId);
+    return false;
+  }
+
+  boundaryOrder(boundary) {
+    return Number.isInteger(boundary.journalSequence) ? boundary.journalSequence : boundary.bridgeCursorAtCommit;
+  }
+
+  previousBoundary(projectId, boundary) {
+    const order = this.boundaryOrder(boundary);
+    return this.conversationStore.listBoundaries(projectId)
+      .filter(candidate => candidate.commitSha !== boundary.commitSha
+        && (candidate.journalId || 'global') === (boundary.journalId || 'global')
+        && this.repoMatches(candidate.repoIdentity, boundary.repoIdentity)
+        && this.boundaryOrder(candidate) < order)
+      .sort((left, right) => this.boundaryOrder(right) - this.boundaryOrder(left))[0] || null;
+  }
+
+  snapshotExists(projectId, commitSha) {
+    return fs.existsSync(this.layout.getProjectCommitConversationPath(projectId, commitSha));
+  }
+
+  async bind(input = {}) {
+    const projectId = validateProjectId(input.projectId);
+    const commitSha = this.layout.validateCommitSha(input.commitSha);
+    if (this.snapshotExists(projectId, commitSha)) return this.conversationStore.readSnapshot(projectId, commitSha);
+
+    if (this.projectStore) await this.conversationStore.importLegacyRequirements(projectId);
+    // Development Conversation reads are centralized: exclusions and Codex
+    // turn repair are identical here and in the query service.
+    let events = readDevelopmentEvents(this.conversationStore, projectId);
+    let boundary = null;
+    try { boundary = this.conversationStore.readBoundary(projectId, commitSha); }
+    catch (error) {
+      if (!error || error.code !== 'ENOENT') throw error;
+    }
+
+    if (boundary) events = events.filter(event => (event.journalId || 'global') === (boundary.journalId || 'global'));
+    const explicitEvents = events.filter(event => event.role === 'user' && event.explicitCommitSha === commitSha);
+    if (!boundary) {
+      const turns = this.buildExplicitTurns(explicitEvents);
+      return this.finalize(projectId, commitSha, {
+        repoIdentity: null,
+        parentSha: null,
+        boundaryStartCursor: null,
+        boundaryEndCursor: null,
+        status: turns.length ? 'available' : 'unavailable',
+        turns,
+        excludedFuturePromptCount: 0,
+      }, { reason: 'missing-commit-boundary' });
+    }
+
+    const previous = this.previousBoundary(projectId, boundary);
+    const state = this.projectStore ? this.projectStore.readState(projectId) : { conversationBaselineCursor: null };
+    const journalId = boundary.journalId || 'global';
+    const baseline = state.conversationBaselineCursors?.[journalId] ?? (journalId === 'global' ? state.conversationBaselineCursor : 0);
+    const startCursor = previous ? previous.bridgeCursorAtCommit : baseline;
+    const endCursor = boundary.bridgeCursorAtCommit;
+    const selected = new Map();
+    let ambiguousCount = 0;
+    let excludedFuturePromptCount = 0;
+
+    for (const event of explicitEvents) {
+      if (event.repoIdentity && boundary.repoIdentity && !this.repoMatches(event.repoIdentity, boundary.repoIdentity)) {
+        ambiguousCount += 1;
+        continue;
+      }
+      if (!event.turnId) { ambiguousCount += 1; continue; }
+      selected.set(event.turnId, 'explicit');
+    }
+
+    if (Number.isInteger(startCursor)) {
+      for (const event of events) {
+        if (event.role !== 'user' || event.sequence == null || event.explicitCommitSha) continue;
+        if (!this.repoMatches(event.repoIdentity, boundary.repoIdentity)) {
+          if (event.sequence > startCursor && event.sequence <= endCursor && !event.repoIdentity) ambiguousCount += 1;
+          continue;
+        }
+        if (event.sequence > endCursor) {
+          excludedFuturePromptCount += 1;
+          continue;
+        }
+        if (event.sequence <= startCursor) continue;
+        // Automatic direct evidence requires exact identity. Legacy stored
+        // 'high'/'trusted' translate to exact for old known data only;
+        // 'explicit' is the explicit-fallback tier (I-18: no synthetic).
+        const rawConfidence = String(event.identityConfidence || '');
+        const effectiveConfidence = rawConfidence === 'high' || rawConfidence === 'trusted' ? 'exact' : rawConfidence;
+        if (!event.turnId || !['exact', 'explicit'].includes(effectiveConfidence)) {
+          ambiguousCount += 1;
+          continue;
+        }
+        selected.set(event.turnId, 'direct');
+      }
+
+      for (const turnId of boundary.openTurnIdsAtCommit) {
+        if (selected.has(turnId)) continue;
+        const user = events.find(event => event.role === 'user'
+          && event.turnId === turnId
+          && event.sequence != null
+          && event.sequence <= startCursor
+          && this.repoMatches(event.repoIdentity, boundary.repoIdentity));
+        const closedAt = user && user.developmentTurnClosedAtSequence;
+        if (user && !(Number.isInteger(closedAt) && closedAt <= startCursor)) {
+          selected.set(turnId, 'shared-spanning');
+        }
+      }
+    }
+
+    const turns = [];
+    for (const [turnId, bindingKind] of selected) {
+      const turnEvents = events.filter(event => event.turnId === turnId).sort((left, right) => {
+        if (left.sequence == null) return 1;
+        if (right.sequence == null) return -1;
+        return left.sequence - right.sequence;
+      });
+      const userEvents = turnEvents.filter(event => event.role === 'user'
+        && (bindingKind === 'explicit' || (event.sequence != null && event.sequence <= endCursor)));
+      if (!userEvents.length) continue;
+      const first = userEvents[0];
+      // I-13: no event beyond the commit boundary may enter a frozen
+      // snapshot — including assistant replies that arrived after the
+      // boundary but before a delayed binder run.
+      const assistantEvents = turnEvents.filter(event => event.role === 'assistant'
+        && (bindingKind === 'explicit' || (event.sequence != null && event.sequence <= endCursor)));
+      turns.push({
+        turnId,
+        source: first.source,
+        sessionId: first.sessionId,
+        bindingKind,
+        userEvents: userEvents.map(projectEvent),
+        assistantEvents: assistantEvents.map(projectEvent),
+      });
+    }
+    turns.sort((left, right) => {
+      const a = left.userEvents[0].sequence;
+      const b = right.userEvents[0].sequence;
+      if (a == null) return 1;
+      if (b == null) return -1;
+      return a - b;
+    });
+
+    let status = turns.length ? 'available' : 'no-new-user-prompt';
+    let reason = turns.length ? 'sequence-window' : 'no-new-user-prompt';
+    if (!Number.isInteger(startCursor)) {
+      status = explicitEvents.length && turns.length ? 'available' : 'unavailable';
+      reason = 'conversation-baseline-unavailable';
+    } else if (ambiguousCount > 0 && !turns.length) {
+      status = 'ambiguous';
+      reason = 'turn-or-repo-identity-ambiguous';
+    }
+
+    return this.finalize(projectId, commitSha, {
+      repoIdentity: boundary.repoIdentity,
+      parentSha: boundary.parentShas[0] || null,
+      boundaryStartCursor: startCursor,
+      boundaryEndCursor: endCursor,
+      status,
+      turns,
+      excludedFuturePromptCount,
+    }, { reason, ambiguousCount, previousBoundaryCommit: previous && previous.commitSha || null });
+  }
+
+  buildExplicitTurns(events) {
+    return events.filter(event => event.turnId).map(event => ({
+      turnId: event.turnId,
+      source: event.source,
+      sessionId: event.sessionId,
+      bindingKind: 'explicit',
+      userEvents: [projectEvent(event)],
+      assistantEvents: [],
+    }));
+  }
+
+  async finalize(projectId, commitSha, snapshotInput, decision) {
+    const snapshot = this.conversationStore.writeSnapshot(projectId, {
+      commitSha,
+      ...snapshotInput,
+      finalizedAt: new Date().toISOString(),
+    });
+    await this.log(snapshot.status === 'ambiguous' || snapshot.status === 'unavailable' ? 'warn' : 'info', 'conversation.commit_snapshot_frozen', 'Commit conversation snapshot was frozen.', {
+      projectId,
+      commitSha,
+      component: 'commit-conversation-binder',
+      phase: 'snapshot-frozen',
+      context: {
+        snapshotHash: snapshot.snapshotHash,
+        status: snapshot.status,
+        turnCount: snapshot.turns.length,
+        userEventCount: snapshot.turns.reduce((total, turn) => total + turn.userEvents.length, 0),
+        assistantEventCount: snapshot.turns.reduce((total, turn) => total + turn.assistantEvents.length, 0),
+        decision,
+      },
+    });
+    return snapshot;
+  }
+}
+
+function snapshotRequirementRecords(snapshot) {
+  return snapshot.turns.flatMap(turn => turn.userEvents.map(event => ({
+    id: event.eventId,
+    client: turn.source,
+    sessionId: turn.sessionId,
+    ts: event.capturedAt,
+    requirement: event.content,
+    requirementHash: event.contentHash,
+    turnId: turn.turnId,
+    bindingKind: turn.bindingKind,
+  })));
+}
+
+module.exports = { CommitConversationBinder, snapshotRequirementRecords, projectEvent, sha256 };

package/_modules/knowledge-engine/src/runtime/commit-processing-ledger.js

@@ -0,0 +1,26 @@
+const fs = require('fs');
+const { DomainError, validateProjectId } = require('./contracts');
+const { validateSha } = require('./scanner');
+const AtomicFile = require('./atomic-file');
+
+class CommitProcessingLedger {
+  constructor(options = {}) { this.layout = options.layout; this.atomic = options.atomic || AtomicFile; }
+  filePath(projectId, commitSha) { return this.layout.getRuntimePath('processed-commits', validateProjectId(projectId), `${validateSha(commitSha)}.json`); }
+  read(projectId, commitSha) {
+    const file = this.filePath(projectId, commitSha);
+    if (!fs.existsSync(file)) return null;
+    return this.atomic.readJsonStrict(file, { category: 'commit-processing-record', validate: value => {
+      if (!value || value.schema !== 'commit-processing-record/v1' || value.projectId !== projectId || value.commitSha !== commitSha || value.status !== 'completed') {
+        throw new DomainError('DATA_CORRUPT', 'Commit processing ledger record is corrupt.', { status: 500 });
+      }
+      return value;
+    } });
+  }
+  complete(projectId, commitSha, fields = {}) {
+    const record = { schema: 'commit-processing-record/v1', projectId: validateProjectId(projectId), commitSha: validateSha(commitSha), status: 'completed', ...fields, completedAt: new Date().toISOString() };
+    this.atomic.writeJsonAtomic(this.filePath(projectId, commitSha), record);
+    return record;
+  }
+}
+
+module.exports = { CommitProcessingLedger };