@sanqianx/project-knowledge 4.7.0 → 4.8.0

package/_modules/knowledge-engine/src/runtime/commit-prompt.js

@@ -0,0 +1,202 @@
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const {
+  DEFAULT_COMMIT_PROMPT_TEMPLATE,
+  PROMPT_TEMPLATE_VERSION,
+  normalizeAutomationConfig,
+  renderTemplate,
+} = require('./automation-config');
+
+const REQUIREMENT_UNAVAILABLE = '需求上下文未记录。只能记录代码可以证明的变化，不得猜测业务目的。';
+const REQUIRED_SECTIONS = Object.freeze([
+  ['userRequirement', '用户需求'],
+  ['aiConversationEvidence', 'AI 对话证据'],
+  ['commitMetadata', 'Commit 信息'],
+  ['actualChanges', 'Commit 实际变更文件'],
+  ['actualPatch', 'Commit 实际 Patch'],
+  ['existingKnowledge', '现有相关知识'],
+]);
+
+function sha256(value) {
+  return `sha256:${crypto.createHash('sha256').update(value, 'utf8').digest('hex')}`;
+}
+
+function formatRequirements(records) {
+  if (!Array.isArray(records) || records.length === 0) return REQUIREMENT_UNAVAILABLE;
+  return records.map(record => [
+    `- requirementId: ${record.id}`,
+    `  client/session: ${record.client}/${record.sessionId}`,
+    `  recordedAt: ${record.ts}`,
+    '  requirement: |',
+    ...String(record.requirement || '').split(/\r?\n/).map(line => `    ${line}`),
+  ].join('\n')).join('\n');
+}
+
+function formatConversationUserTruth(snapshot) {
+  if (!snapshot || !Array.isArray(snapshot.turns) || snapshot.turns.length === 0) return REQUIREMENT_UNAVAILABLE;
+  return snapshot.turns.flatMap(turn => turn.userEvents.map(event => [
+    `- turnId: ${turn.turnId}`,
+    `  eventId: ${event.eventId}`,
+    `  source/session: ${turn.source}/${turn.sessionId || '(unavailable)'}`,
+    `  binding: ${turn.bindingKind}`,
+    `  capturedAt: ${event.capturedAt}`,
+    '  userPrompt: |',
+    ...String(event.content || '').split(/\r?\n/).map(line => `    ${line}`),
+  ].join('\n'))).join('\n');
+}
+
+function formatAssistantEvidence(snapshot) {
+  if (!snapshot || !Array.isArray(snapshot.turns)) return '(no assistant conversation evidence was frozen)';
+  const entries = snapshot.turns.flatMap(turn => turn.assistantEvents.map(event => [
+    `- turnId: ${turn.turnId}`,
+    `  eventId: ${event.eventId}`,
+    `  capturedAt: ${event.capturedAt}`,
+    '  assistantResponse: |',
+    ...String(event.content || '').split(/\r?\n/).map(line => `    ${line}`),
+  ].join('\n')));
+  return entries.length ? entries.join('\n') : '(no assistant conversation evidence was frozen)';
+}
+
+function formatCommitMetadata(evidence) {
+  return [
+    `fullSha: ${evidence.commitSha}`,
+    `parents: ${(evidence.parents || []).join(', ') || '(root commit)'}`,
+    `author: ${evidence.author || ''}`,
+    `date: ${evidence.date || ''}`,
+    `subject: ${evidence.subject || ''}`,
+    `branchAtScan: ${evidence.branch || '(detached/unavailable)'}`,
+    `patchMode: ${evidence.patchMode}`,
+    `patchHash: ${evidence.patchHash}`,
+    `patchBytes: ${evidence.patchBytes}`,
+  ].join('\n');
+}
+
+function formatChanges(evidence) {
+  if (!evidence.files || evidence.files.length === 0) return '(no changed paths reported by Git)';
+  return evidence.files.map(file => {
+    const rename = file.oldPath ? ` ${file.oldPath} -> ${file.path}` : ` ${file.path}`;
+    const stats = file.binary ? ' binary' : ` +${file.added == null ? '?' : file.added}/-${file.deleted == null ? '?' : file.deleted}`;
+    return `- ${file.status}${rename}${stats}`;
+  }).join('\n');
+}
+
+function formatPatch(evidence) {
+  if (!evidence.patchChunked) return evidence.patch || '(empty patch)';
+  const bundle = evidence.evidenceBundle || {};
+  return [
+    '[EXACT PATCH AVAILABLE AS READ-ONLY CHUNKS]',
+    `fullPatchHash: ${evidence.patchHash}`,
+    `fullPatchBytes: ${evidence.patchBytes}`,
+    `patchManifestHash: ${bundle.manifestHash || '(unavailable)'}`,
+    `patchManifestPath: ${bundle.manifestPath || '(unavailable)'}`,
+    `chunkCount: ${bundle.chunkCount == null ? '(unavailable)' : bundle.chunkCount}`,
+    'Read patch-manifest.json, then Read exact patch chunks in manifest sequence. The chunks cover the full Git diff.',
+    'Do not read the source worktree and do not infer unread evidence.',
+  ].join('\n');
+}
+
+function formatExistingKnowledge(existing) {
+  if (!existing || !Array.isArray(existing.entries) || existing.entries.length === 0) {
+    return '(no existing project knowledge was available)';
+  }
+  const sections = existing.entries.map(entry => `--- ${entry.path} (${entry.hash}) ---\n${entry.content}`);
+  if (existing.omitted && existing.omitted.length) {
+    sections.push(`[EXISTING KNOWLEDGE OMITTED: ${existing.omitted.join(', ')}]`);
+  }
+  return sections.join('\n\n');
+}
+
+function ensureRequiredSections(template, rendered, vars) {
+  const missing = REQUIRED_SECTIONS.filter(([name]) => !new RegExp(`\\{\\{\\s*${name}\\s*\\}\\}`, 'i').test(template));
+  if (!missing.length) return rendered;
+  const footer = missing.map(([name, label]) => `${label}：\n${vars[name]}`).join('\n\n');
+  return `${rendered.trimEnd()}\n\n${footer}`;
+}
+
+function renderCommitPrompt(input = {}) {
+  const config = input.config || {};
+  const evidence = input.evidence || {};
+  const automation = normalizeAutomationConfig(config.automation);
+  const template = automation.commitPromptTemplate || DEFAULT_COMMIT_PROMPT_TEMPLATE;
+  const vars = {
+    userRequirement: input.conversationSnapshot
+      ? formatConversationUserTruth(input.conversationSnapshot)
+      : formatRequirements(input.requirements),
+    aiConversationEvidence: formatAssistantEvidence(input.conversationSnapshot),
+    commitMetadata: formatCommitMetadata(evidence),
+    actualChanges: formatChanges(evidence),
+    actualPatch: formatPatch(evidence),
+    existingKnowledge: formatExistingKnowledge(input.existingKnowledge),
+    projectId: config.projectId || input.projectId || '',
+    displayName: config.displayName || config.projectId || '',
+    knowledgePath: config.knowledgePath || '',
+    repoPath: config.repoPath || '',
+    commitHash: evidence.commitSha || '',
+    commitSubject: evidence.subject || '',
+    commitAuthor: evidence.author || '',
+    commitDate: evidence.date || '',
+    branch: evidence.branch || '',
+    changedFiles: formatChanges(evidence),
+    diffSummary: formatPatch(evidence),
+  };
+  const rendered = ensureRequiredSections(template, renderTemplate(template, vars), vars).trimEnd() + '\n';
+  return {
+    prompt: rendered,
+    promptHash: sha256(rendered),
+    promptTemplateVersion: PROMPT_TEMPLATE_VERSION,
+    promptLength: rendered.length,
+    vars,
+  };
+}
+
+class KnowledgeEvidenceReader {
+  constructor(options = {}) {
+    this.maxBytes = Number(options.maxBytes || 256 * 1024);
+    this.maxFiles = Number(options.maxFiles || 24);
+  }
+
+  read(config) {
+    const root = config && config.knowledgePath ? path.resolve(config.knowledgePath) : '';
+    if (!root || !fs.existsSync(root) || !fs.statSync(root).isDirectory()) return { entries: [], omitted: [] };
+    const realRoot = fs.realpathSync(root);
+    const files = [];
+    const walk = current => {
+      for (const entry of fs.readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (entry.isSymbolicLink()) continue;
+        const absolute = path.join(current, entry.name);
+        if (entry.isDirectory()) walk(absolute);
+        else if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) files.push(absolute);
+      }
+    };
+    walk(root);
+    let used = 0;
+    const entries = [];
+    const omitted = [];
+    for (const file of files) {
+      const realFile = fs.realpathSync(file);
+      const relativeBoundary = path.relative(realRoot, realFile);
+      if (relativeBoundary.startsWith('..') || path.isAbsolute(relativeBoundary)) continue;
+      const relativePath = path.relative(root, file).replace(/\\/g, '/');
+      const content = fs.readFileSync(file, 'utf8');
+      const bytes = Buffer.byteLength(content, 'utf8');
+      if (entries.length >= this.maxFiles || used + bytes > this.maxBytes) {
+        omitted.push(relativePath);
+        continue;
+      }
+      used += bytes;
+      entries.push({ path: relativePath, hash: sha256(content), content });
+    }
+    return { entries, omitted, totalBytes: used, limitBytes: this.maxBytes, limitFiles: this.maxFiles };
+  }
+}
+
+module.exports = {
+  REQUIREMENT_UNAVAILABLE,
+  KnowledgeEvidenceReader,
+  formatRequirements,
+  formatConversationUserTruth,
+  formatAssistantEvidence,
+  renderCommitPrompt,
+  sha256,
+};

package/_modules/knowledge-engine/src/runtime/commit-reconciler.js

@@ -0,0 +1,432 @@
+const fs = require('fs');
+const path = require('path');
+const AtomicFile = require('./atomic-file');
+const {
+  SCHEMAS,
+  DomainError,
+  createId,
+  validateProjectId,
+  validateTrigger,
+} = require('./contracts');
+const { CommitScanner, validateSha } = require('./scanner');
+const { ConversationStore } = require('./conversation-store');
+const { CommitConversationBinder, snapshotRequirementRecords } = require('./commit-conversation-binder');
+const { renderCommitPrompt, sha256 } = require('./commit-prompt');
+const { KnowledgeRetrievalService } = require('./knowledge-retrieval-service');
+const { manifestHash: calculateRetrievalManifestHash } = require('./knowledge-retrieval-service');
+const { sha256: knowledgeContentHash } = require('./content-hash');
+const { CommitProcessingLedger } = require('./commit-processing-ledger');
+
+const explicitQueues = new Map();
+
+function publicFailure(error, phase) {
+  return {
+    code: error && error.code || 'INVALID_ARGUMENT',
+    message: String(error && error.message || 'Commit reconciliation failed.'),
+    phase,
+    retryable: error && error.retryable === true,
+    ts: new Date().toISOString(),
+  };
+}
+
+function validateClaim(claim, projectId, commitSha) {
+  if (!claim || typeof claim !== 'object' || claim.schema !== SCHEMAS.commitClaim) {
+    throw new DomainError('DATA_CORRUPT', 'Active commit claim is corrupt.', { status: 500 });
+  }
+  if (claim.projectId !== projectId || claim.commitSha !== commitSha) {
+    throw new DomainError('DATA_CORRUPT', 'Active commit claim identity does not match the pending commit.', { status: 500 });
+  }
+  if (!Array.isArray(claim.requirementIds) || !claim.patchHash || !claim.promptHash || !claim.evidenceHash
+    || !claim.evidenceManifestHash || !claim.retrievalManifestHash || !claim.knowledgePath || !claim.runId) {
+    throw new DomainError('DATA_CORRUPT', 'Active commit claim is incomplete.', { status: 500 });
+  }
+  return claim;
+}
+
+function claimFingerprint(claim) {
+  return sha256(JSON.stringify({
+    schema: claim.schema,
+    projectId: claim.projectId,
+    commitSha: claim.commitSha,
+    parents: claim.parents,
+    requirementIds: claim.requirementIds,
+    requirementBinding: claim.requirementBinding,
+    conversationSnapshotHash: claim.conversationSnapshotHash || '',
+    promptTemplateVersion: claim.promptTemplateVersion,
+    promptHash: claim.promptHash,
+    patchHash: claim.patchHash,
+    evidenceHash: claim.evidenceHash,
+    evidenceManifestHash: claim.evidenceManifestHash,
+    retrievalManifestHash: claim.retrievalManifestHash,
+    knowledgePath: claim.knowledgePath,
+  }));
+}
+
+class CommitClaimStore {
+  constructor(options = {}) {
+    this.layout = options.layout;
+    this.atomic = options.atomic || AtomicFile;
+  }
+
+  filePath(projectId, commitSha) {
+    return this.layout.getRuntimePath('claims', validateProjectId(projectId), `${validateSha(commitSha)}.json`);
+  }
+
+  write(projectId, commitSha, snapshot) {
+    const file = this.filePath(projectId, commitSha);
+    this.atomic.writeJsonAtomic(file, { schema: 'commit-claim-snapshot/v1', ...snapshot });
+    return file;
+  }
+
+  read(projectId, commitSha) {
+    return this.atomic.readJsonStrict(this.filePath(projectId, commitSha), {
+      category: 'commit-claim-snapshot',
+      validate: snapshot => {
+        if (!snapshot || snapshot.schema !== 'commit-claim-snapshot/v1' || snapshot.projectId !== projectId || snapshot.commitSha !== commitSha) {
+          throw new DomainError('DATA_CORRUPT', 'Commit claim snapshot is corrupt.', { status: 500 });
+        }
+        return snapshot;
+      },
+    });
+  }
+
+  remove(projectId, commitSha) {
+    const file = this.filePath(projectId, commitSha);
+    try { fs.unlinkSync(file); } catch (error) { if (!error || error.code !== 'ENOENT') throw error; }
+  }
+}
+
+class CommitReconciler {
+  constructor(options = {}) {
+    this.layout = options.layout;
+    this.registryStore = options.registryStore;
+    this.projectStore = options.projectStore;
+    this.scanner = options.scanner || new CommitScanner(options);
+    this.conversationStore = options.conversationStore || new ConversationStore({
+      layout: this.layout,
+      projectStore: this.projectStore,
+      logger: options.logger,
+    });
+    this.binder = options.conversationBinder || new CommitConversationBinder({
+      layout: this.layout,
+      projectStore: this.projectStore,
+      conversationStore: this.conversationStore,
+      logger: options.logger,
+    });
+    this.retrievalService = options.retrievalService || new KnowledgeRetrievalService({
+      layout: this.layout,
+      registryStore: this.registryStore,
+      projectStore: this.projectStore,
+      databaseProvider: options.databaseProvider,
+      embedderProvider: options.embedderProvider,
+      logger: options.logger,
+    });
+    this.claimStore = options.claimStore || new CommitClaimStore({ layout: this.layout });
+    this.processingLedger = options.processingLedger || new CommitProcessingLedger({ layout: this.layout });
+    this.claimProcessor = options.claimProcessor || null;
+    this.logger = options.logger || null;
+    this.batchSize = Math.max(1, Number(options.batchSize || 200));
+  }
+
+  async log(level, event, message, context) {
+    if (this.logger && typeof this.logger[level] === 'function') await this.logger[level](event, message, context);
+  }
+
+  async reconcile(projectId, trigger, context = {}) {
+    validateProjectId(projectId);
+    validateTrigger(trigger);
+    if (!context.commitSha) throw new DomainError('INVALID_ARGUMENT', 'Commit reconciliation requires an explicit Hook commit SHA.');
+    return this.processCommitEvent({ projectId, commitSha: context.commitSha, branch: context.branch || '', operationId: context.operationId || createId('op') });
+  }
+
+  async processCommitEvent({ projectId, commitSha, branch = '', operationId = '' } = {}) {
+    validateProjectId(projectId);
+    validateSha(commitSha);
+    const existingQueue = explicitQueues.get(projectId) || { tail: Promise.resolve(), pending: new Map() };
+    explicitQueues.set(projectId, existingQueue);
+    if (existingQueue.pending.has(commitSha)) return existingQueue.pending.get(commitSha);
+    const queued = existingQueue.tail.catch(() => {}).then(async () => {
+      const completed = this.processingLedger.read(projectId, commitSha);
+      if (completed) return { ok: true, projectId, commitSha, status: 'already-completed', processed: [], ledger: completed };
+      const config = this.projectStore.readConfig(projectId);
+      if (config.enabled === false) return { ok: true, projectId, commitSha, status: 'disabled', processed: [] };
+      const result = await this.processCommit(projectId, 'git-hook', operationId || createId('op'), config, branch, commitSha);
+      if (!result.ok) return { ok: false, projectId, commitSha, status: 'failed', processed: [result], error: result.error };
+      const ledger = this.processingLedger.complete(projectId, commitSha, { runId: result.runId, claimFingerprint: result.claimFingerprint || '' });
+      return { ok: true, projectId, commitSha, status: 'completed', processed: [result], ledger };
+    });
+    existingQueue.pending.set(commitSha, queued);
+    existingQueue.tail = queued.catch(() => {});
+    try { return await queued; }
+    finally {
+      existingQueue.pending.delete(commitSha);
+      if (!existingQueue.pending.size) explicitQueues.delete(projectId);
+    }
+  }
+
+  async prepareClaim(projectId, trigger, operationId, config, branch, commitSha) {
+    const state = this.projectStore.readState(projectId);
+    if (state.analysis.activeClaim) {
+      const activeClaim = state.analysis.activeClaim;
+      // A terminal failure must not turn a project into a permanent dead end.
+      // We only release it while processing a *new, explicit* Hook SHA; the
+      // failed SHA is never retried, scanned, or inferred from history.
+      if (activeClaim.commitSha !== commitSha) {
+        validateClaim(activeClaim, projectId, activeClaim.commitSha);
+        const terminalFailure = activeClaim.phase === 'failed'
+          && activeClaim.error
+          && activeClaim.error.retryable !== true;
+        if (!terminalFailure) {
+          throw new DomainError('PROJECT_BUSY', 'Another unfinished commit claim already exists.', { status: 409, retryable: true });
+        }
+        await this.projectStore.updateState(projectId, draft => {
+          const current = draft.analysis.activeClaim;
+          if (!current || current.commitSha !== activeClaim.commitSha || current.fingerprint !== activeClaim.fingerprint) {
+            throw new DomainError('PROJECT_BUSY', 'The active commit claim changed while preparing this Hook event.', { status: 409, retryable: true });
+          }
+          draft.analysis.activeClaim = null;
+          draft.analysis.status = 'idle';
+          draft.analysis.lastError = {
+            code: 'FAILED_CLAIM_SUPERSEDED',
+            message: 'A terminal failed claim was preserved for diagnostics and superseded by a newer explicit Hook commit.',
+            retryable: false,
+            ts: new Date().toISOString(),
+          };
+        });
+        await this.log('warn', 'reconcile.failed_claim_superseded', 'A terminal failed claim was superseded by a newer explicit Hook commit.', {
+          projectId,
+          previousCommitSha: activeClaim.commitSha,
+          commitSha,
+          previousFailure: activeClaim.error,
+        });
+        return this.prepareClaim(projectId, trigger, operationId, config, branch, commitSha);
+      }
+      const claim = validateClaim(activeClaim, projectId, commitSha);
+      const snapshot = this.claimStore.read(projectId, commitSha);
+      if (snapshot.claimFingerprint !== claimFingerprint(claim)
+        || snapshot.evidence.patchHash !== claim.patchHash
+        || snapshot.evidence.evidenceHash !== claim.evidenceHash
+        || !snapshot.evidence.evidenceBundle
+        || snapshot.evidence.evidenceBundle.manifestHash !== claim.evidenceManifestHash
+        || !snapshot.existingKnowledge || snapshot.existingKnowledge.manifestHash !== claim.retrievalManifestHash
+        || sha256(snapshot.prompt) !== claim.promptHash
+        || (claim.conversationSnapshotHash && (!snapshot.conversationSnapshot || snapshot.conversationSnapshot.snapshotHash !== claim.conversationSnapshotHash))) {
+        throw new DomainError('DATA_CORRUPT', 'Frozen commit claim snapshot does not match active state.', { status: 500 });
+      }
+      this.scanner.verifyEvidence(snapshot.evidence);
+      const retrievalManifest = this.claimStore.atomic.readJsonStrict(snapshot.existingKnowledge.manifestPath, {
+        category: 'knowledge-retrieval-manifest',
+        validate: value => {
+          if (!value || value.schema !== 'knowledge-retrieval-manifest/v1'
+            || value.manifestHash !== claim.retrievalManifestHash
+            || calculateRetrievalManifestHash(value) !== value.manifestHash) {
+            throw new DomainError('DATA_CORRUPT', 'Frozen knowledge retrieval manifest is corrupt.', { status: 500 });
+          }
+          return value;
+        },
+      });
+      const selectedById = new Map(retrievalManifest.selected.map(item => [`${item.spaceId}:${item.chunkId}`, item]));
+      for (const entry of snapshot.existingKnowledge.entries || []) {
+        const selected = selectedById.get(`${entry.spaceId || `project:${entry.projectId}`}:${entry.chunkId}`);
+        if (!selected || knowledgeContentHash(entry.content) !== entry.hash || selected.contentHash !== entry.hash) {
+          throw new DomainError('DATA_CORRUPT', 'Frozen authoritative Markdown context does not match its retrieval manifest.', { status: 500 });
+        }
+      }
+      claim.attempt = Number(claim.attempt || 1) + 1;
+      claim.phase = 'evidence.prepared';
+      await this.projectStore.updateState(projectId, draft => {
+        draft.analysis.activeClaim = claim;
+        draft.analysis.status = 'evidence.prepared';
+        draft.analysis.lastError = null;
+      });
+      return {
+        claim,
+        evidence: snapshot.evidence,
+        prompt: snapshot.prompt,
+        requirements: snapshot.requirements || [],
+        conversationSnapshot: snapshot.conversationSnapshot || null,
+        existingKnowledge: snapshot.existingKnowledge,
+        retry: true,
+      };
+    }
+
+    const runId = createId('run');
+    const evidenceRoot = this.layout.getRuntimePath('runs', projectId, runId, 'input', 'evidence');
+    const evidence = await this.scanner.collectEvidence(config, commitSha, { branch, evidenceRoot });
+    this.scanner.verifyEvidence(evidence);
+    const conversationSnapshot = await this.binder.bind({ projectId, commitSha, branch });
+    const requirements = snapshotRequirementRecords(conversationSnapshot);
+    const existingKnowledge = await this.retrievalService.retrieveForCommit({
+      projectId,
+      conversationSnapshot,
+      commitEvidence: evidence,
+    });
+    existingKnowledge.manifestPath = this.layout.getRuntimePath('runs', projectId, runId, 'input', 'retrieval', 'manifest.json');
+    this.claimStore.atomic.writeJsonAtomic(existingKnowledge.manifestPath, existingKnowledge.manifest);
+    const rendered = renderCommitPrompt({ projectId, config, evidence, requirements, conversationSnapshot, existingKnowledge });
+    const claim = {
+      schema: SCHEMAS.commitClaim,
+      projectId,
+      commitSha,
+      parents: evidence.parents,
+      triggerFirstSeen: trigger,
+      requirementIds: requirements.map(requirement => requirement.id),
+      requirementBinding: conversationSnapshot.status,
+      conversationSnapshotHash: conversationSnapshot.snapshotHash,
+      conversationTurnIds: conversationSnapshot.turns.map(turn => turn.turnId),
+      conversationEventIds: conversationSnapshot.turns.flatMap(turn => [...turn.userEvents, ...turn.assistantEvents].map(event => event.eventId)),
+      promptTemplateVersion: rendered.promptTemplateVersion,
+      promptHash: rendered.promptHash,
+      patchHash: evidence.patchHash,
+      evidenceHash: evidence.evidenceHash,
+      evidenceManifestHash: evidence.evidenceBundle.manifestHash,
+      retrievalManifestHash: existingKnowledge.manifestHash,
+      knowledgePath: config.knowledgePath,
+      runId,
+      operationId,
+      phase: 'evidence.prepared',
+      attempt: 1,
+    };
+    claim.fingerprint = claimFingerprint(claim);
+    this.claimStore.write(projectId, commitSha, {
+      projectId,
+      commitSha,
+      claimFingerprint: claim.fingerprint,
+      evidence,
+      prompt: rendered.prompt,
+      requirements,
+      conversationSnapshot,
+      existingKnowledge,
+      createdAt: new Date().toISOString(),
+    });
+    try {
+      await this.projectStore.updateState(projectId, draft => {
+        if (draft.analysis.activeClaim) throw new DomainError('PROJECT_BUSY', 'Another active claim already exists.', { status: 409, retryable: true });
+        draft.analysis.activeClaim = claim;
+        draft.analysis.status = 'evidence.prepared';
+        draft.analysis.lastError = null;
+      });
+    } catch (error) {
+      this.claimStore.remove(projectId, commitSha);
+      throw error;
+    }
+    await this.log('info', 'reconcile.claim_prepared', 'Commit evidence and claim prepared.', {
+      projectId,
+      operationId,
+      runId: claim.runId,
+      commitSha,
+      phase: claim.phase,
+      promptHash: claim.promptHash,
+      patchHash: claim.patchHash,
+      patchBytes: evidence.patchBytes,
+      evidenceManifestHash: claim.evidenceManifestHash,
+      evidenceChunkCount: evidence.evidenceBundle.chunkCount,
+      evidenceChunkBytes: evidence.evidenceBundle.chunkBytes,
+      retrievalManifestHash: claim.retrievalManifestHash,
+      retrievalSelectedCount: existingKnowledge.entries.length,
+      retrievalBytes: existingKnowledge.totalBytes,
+      fileCount: evidence.files.length,
+      requirementBinding: claim.requirementBinding,
+      requirementCount: claim.requirementIds.length,
+    });
+    return { claim, evidence, prompt: rendered.prompt, requirements, conversationSnapshot, existingKnowledge, retry: false };
+  }
+
+  async processCommit(projectId, trigger, operationId, config, branch, commitSha) {
+    let prepared;
+    try {
+      prepared = await this.prepareClaim(projectId, trigger, operationId, config, branch, commitSha);
+      // Runtime configuration is resolved by the headless analyzer. This
+      // service must never load the shell's settings or persist credentials.
+      if (!this.claimProcessor || typeof this.claimProcessor.processClaim !== 'function') {
+        throw new DomainError('INVALID_ARGUMENT', 'Knowledge claim processor is unavailable.', { status: 503, retryable: true });
+      }
+      const result = await this.claimProcessor.processClaim({
+        projectId,
+        config,
+        claim: prepared.claim,
+        evidence: prepared.evidence,
+        prompt: prepared.prompt,
+        requirements: prepared.requirements,
+        conversationSnapshot: prepared.conversationSnapshot,
+        existingKnowledge: prepared.existingKnowledge,
+        operationId,
+      });
+      if (!result || result.stateAdvanced !== true) {
+        throw new DomainError('INVALID_ARGUMENT', 'Knowledge promotion did not prove state advancement.', { status: 500, retryable: true });
+      }
+      const advanced = this.projectStore.readState(projectId);
+      if (advanced.lastAnalyzedCommit !== commitSha || advanced.analysis.activeClaim) {
+        throw new DomainError('DATA_CORRUPT', 'Claim processor reported success without atomically advancing project state.', { status: 500 });
+      }
+      this.claimStore.remove(projectId, commitSha);
+      await this.log('info', 'reconcile.commit_completed', 'Commit knowledge was promoted and state advanced.', {
+        projectId,
+        operationId,
+        runId: prepared.claim.runId,
+        commitSha,
+        phase: 'state.advanced',
+      });
+      return { ok: true, commitSha, runId: prepared.claim.runId, claimFingerprint: prepared.claim.fingerprint, retry: prepared.retry };
+    } catch (error) {
+      const failure = publicFailure(error, prepared && prepared.claim && prepared.claim.phase || 'evidence.prepared');
+      let stateUpdateError = null;
+      try {
+        await this.projectStore.updateState(projectId, draft => {
+          const active = draft.analysis.activeClaim;
+          if (active && active.commitSha === commitSha) {
+            active.phase = 'failed';
+            active.error = failure;
+          }
+          draft.analysis.status = 'failed';
+          draft.analysis.lastError = failure;
+        });
+      } catch (updateError) {
+        stateUpdateError = updateError;
+      }
+      await this.log('error', 'reconcile.commit_failed', 'Commit reconciliation stopped at the first failed commit.', {
+        projectId,
+        operationId,
+        runId: prepared && prepared.claim && prepared.claim.runId,
+        commitSha,
+        phase: failure.phase,
+        error,
+        context: stateUpdateError ? { failureStateWriteError: stateUpdateError } : {},
+      });
+      return { ok: false, commitSha, error: failure, retry: prepared && prepared.retry || false };
+    }
+  }
+
+  async markDiverged(projectId, operationId, message, processed = []) {
+    const error = new DomainError('HISTORY_DIVERGED', message || 'Git history diverged from the stored baseline.', { status: 409 });
+    await this.projectStore.updateState(projectId, state => {
+      state.analysis.status = 'history-diverged';
+      state.analysis.lastError = publicFailure(error, 'history-diverged');
+    });
+    await this.log('error', 'reconcile.history_diverged', 'Git history diverged; reconciliation stopped without moving pointers.', { projectId, operationId, phase: 'history-diverged', error });
+    return { ok: false, status: 'history-diverged', processed, error: publicFailure(error, 'history-diverged') };
+  }
+
+  async failWithoutClaim(projectId, operationId, error, phase, processed = []) {
+    await this.projectStore.updateState(projectId, state => {
+      state.analysis.status = 'failed';
+      state.analysis.lastError = publicFailure(error, phase);
+    });
+    await this.log('error', 'reconcile.failed', 'Reconciliation failed before claim processing.', { projectId, operationId, phase, error });
+    return { ok: false, status: 'failed', processed, error: publicFailure(error, phase) };
+  }
+}
+
+async function reconcileProjectCommits(projectId, trigger, deps = {}) {
+  const reconciler = deps.reconciler instanceof CommitReconciler ? deps.reconciler : new CommitReconciler(deps);
+  return reconciler.reconcile(projectId, trigger, { operationId: deps.operationId || '', commitSha: deps.commitSha || '', branch: deps.branch || '' });
+}
+
+module.exports = {
+  CommitClaimStore,
+  CommitReconciler,
+  CommitProcessingLedger,
+  claimFingerprint,
+  reconcileProjectCommits,
+  validateClaim,
+};

package/_modules/knowledge-engine/src/runtime/content-hash.js

@@ -0,0 +1,4 @@
+'use strict';
+const crypto = require('node:crypto');
+function sha256(value) { return crypto.createHash('sha256').update(String(value || ''), 'utf8').digest('hex'); }
+module.exports = { sha256 };