@sanqianx/project-knowledge 4.7.0 → 4.8.0

package/_modules/knowledge-engine/src/runtime/conversation-store.js

@@ -0,0 +1,387 @@
+const fs = require('fs');
+const crypto = require('crypto');
+const { SCHEMAS, DomainError, validateProjectId } = require('./contracts');
+const AtomicFile = require('./atomic-file');
+
+const SOURCES = new Set(['claude-code', 'codex', 'opencode']);
+const ROLES = new Set(['user', 'assistant', null]);
+const SNAPSHOT_STATUSES = new Set(['available', 'no-new-user-prompt', 'unavailable', 'ambiguous']);
+const BINDING_KINDS = new Set(['direct', 'shared-spanning', 'explicit']);
+
+function sha256(value) {
+  return `sha256:${crypto.createHash('sha256').update(String(value == null ? '' : value), 'utf8').digest('hex')}`;
+}
+
+function optionalString(value) {
+  if (value == null || value === '') return null;
+  return String(value);
+}
+
+function validateConversationEvent(event, expectedProjectId = '') {
+  if (!event || typeof event !== 'object' || Array.isArray(event)) throw new DomainError('INVALID_ARGUMENT', 'Conversation event is invalid.');
+  if (event.schema !== SCHEMAS.aiCodingEvent) throw new DomainError('SCHEMA_UNSUPPORTED', 'Conversation event must use ai-coding-event/v1.', { status: 409 });
+  const projectId = validateProjectId(event.projectId);
+  if (expectedProjectId && projectId !== expectedProjectId) throw new DomainError('INVALID_ARGUMENT', 'Conversation event projectId does not match the store.');
+  if (!event.eventId || typeof event.eventId !== 'string') throw new DomainError('INVALID_ARGUMENT', 'Conversation eventId is required.');
+  if (event.sequence != null && (!Number.isInteger(event.sequence) || event.sequence < 0)) throw new DomainError('INVALID_ARGUMENT', 'Conversation sequence must be a non-negative integer or null.');
+  if (!SOURCES.has(event.source)) throw new DomainError('INVALID_ARGUMENT', 'Conversation source is invalid.');
+  if (!event.eventType || typeof event.eventType !== 'string') throw new DomainError('INVALID_ARGUMENT', 'Conversation eventType is required.');
+  if (!ROLES.has(event.role)) throw new DomainError('INVALID_ARGUMENT', 'Conversation role is invalid.');
+  if (event.role && typeof event.content !== 'string') throw new DomainError('INVALID_ARGUMENT', 'User and assistant events require text content.');
+  if (!event.capturedAt || Number.isNaN(Date.parse(event.capturedAt))) throw new DomainError('INVALID_ARGUMENT', 'Conversation capturedAt must be an ISO timestamp.');
+  if (event.contentHash !== sha256(event.content || '')) throw new DomainError('DATA_CORRUPT', 'Conversation content hash does not match.', { status: 409 });
+  return event;
+}
+
+function normalizeConversationEvent(projectId, input = {}) {
+  validateProjectId(projectId);
+  const role = input.role == null ? null : String(input.role);
+  const content = role ? String(input.content == null ? '' : input.content) : '';
+  const normalized = {
+    schema: SCHEMAS.aiCodingEvent,
+    projectId,
+    eventId: String(input.eventId || '').trim(),
+    sequence: input.sequence == null ? null : Number(input.sequence),
+    journalId: optionalString(input.journalId) || 'global',
+    source: String(input.source || ''),
+    eventType: String(input.eventType || ''),
+    role,
+    content,
+    contentHash: sha256(content),
+    sessionId: optionalString(input.sessionId),
+    turnId: optionalString(input.turnId),
+    projectPath: optionalString(input.projectPath),
+    repoIdentity: input.repoIdentity && typeof input.repoIdentity === 'object' ? { ...input.repoIdentity } : null,
+    branch: optionalString(input.branch),
+    headAtCapture: optionalString(input.headAtCapture),
+    capturedAt: input.capturedAt || new Date().toISOString(),
+    rawEventType: optionalString(input.rawEventType),
+    identityConfidence: optionalString(input.identityConfidence) || 'unknown',
+    captureStatus: optionalString(input.captureStatus) || 'captured',
+    explicitCommitSha: optionalString(input.explicitCommitSha),
+    legacyRequirementId: optionalString(input.legacyRequirementId),
+  };
+  return validateConversationEvent(normalized, projectId);
+}
+
+function readJsonlStrict(filePath, validator, category) {
+  if (!fs.existsSync(filePath)) return [];
+  const records = [];
+  const lines = fs.readFileSync(filePath, 'utf8').split(/\r?\n/);
+  for (let index = 0; index < lines.length; index += 1) {
+    if (!lines[index].trim()) continue;
+    try {
+      records.push(validator(JSON.parse(lines[index])));
+    } catch (error) {
+      if (error instanceof DomainError) throw error;
+      throw new DomainError('DATA_CORRUPT', `${category} JSONL is corrupt.`, { status: 500, cause: error, details: { line: index + 1 } });
+    }
+  }
+  return records;
+}
+
+function appendJsonlDurable(filePath, value) {
+  fs.mkdirSync(require('path').dirname(filePath), { recursive: true });
+  const line = Buffer.from(`${JSON.stringify(value)}\n`, 'utf8');
+  const fd = fs.openSync(filePath, 'a', 0o600);
+  try {
+    fs.writeSync(fd, line, 0, line.length, null);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function validateBoundary(boundary, expectedProjectId = '', expectedCommitSha = '') {
+  if (!boundary || typeof boundary !== 'object' || boundary.schema !== SCHEMAS.gitCommitBoundary) {
+    throw new DomainError('SCHEMA_UNSUPPORTED', 'Commit boundary must use git-commit-boundary/v1.', { status: 409 });
+  }
+  validateProjectId(boundary.projectId);
+  if (expectedProjectId && boundary.projectId !== expectedProjectId) throw new DomainError('DATA_CORRUPT', 'Commit boundary projectId mismatch.', { status: 500 });
+  if (!boundary.commitSha || (expectedCommitSha && boundary.commitSha !== expectedCommitSha)) throw new DomainError('DATA_CORRUPT', 'Commit boundary SHA mismatch.', { status: 500 });
+  if (!Number.isInteger(boundary.bridgeCursorAtCommit) || boundary.bridgeCursorAtCommit < 0) throw new DomainError('INVALID_ARGUMENT', 'Commit boundary cursor is invalid.');
+  if (boundary.journalSequence != null && (!Number.isInteger(boundary.journalSequence) || boundary.journalSequence < 0)) throw new DomainError('INVALID_ARGUMENT', 'Commit boundary journal sequence is invalid.');
+  if (!Array.isArray(boundary.parentShas) || !Array.isArray(boundary.openTurnIdsAtCommit)) throw new DomainError('INVALID_ARGUMENT', 'Commit boundary collections are invalid.');
+  if (!boundary.operationId || !boundary.committedAt) throw new DomainError('INVALID_ARGUMENT', 'Commit boundary operation metadata is required.');
+  return boundary;
+}
+
+function snapshotPayload(snapshot) {
+  const { snapshotHash, ...payload } = snapshot;
+  return payload;
+}
+
+function validateSnapshot(snapshot, expectedProjectId = '', expectedCommitSha = '') {
+  if (!snapshot || typeof snapshot !== 'object' || snapshot.schema !== SCHEMAS.commitConversationSnapshot) {
+    throw new DomainError('SCHEMA_UNSUPPORTED', 'Commit conversation snapshot must use commit-conversation-snapshot/v1.', { status: 409 });
+  }
+  validateProjectId(snapshot.projectId);
+  if (expectedProjectId && snapshot.projectId !== expectedProjectId) throw new DomainError('DATA_CORRUPT', 'Conversation snapshot projectId mismatch.', { status: 500 });
+  if (!snapshot.commitSha || (expectedCommitSha && snapshot.commitSha !== expectedCommitSha)) throw new DomainError('DATA_CORRUPT', 'Conversation snapshot SHA mismatch.', { status: 500 });
+  if (!SNAPSHOT_STATUSES.has(snapshot.status) || !Array.isArray(snapshot.turns)) throw new DomainError('INVALID_ARGUMENT', 'Conversation snapshot status or turns are invalid.');
+  for (const turn of snapshot.turns) {
+    if (!turn.turnId || !BINDING_KINDS.has(turn.bindingKind) || !Array.isArray(turn.userEvents) || !Array.isArray(turn.assistantEvents)) {
+      throw new DomainError('INVALID_ARGUMENT', 'Conversation snapshot turn is invalid.');
+    }
+    for (const event of [...turn.userEvents, ...turn.assistantEvents]) {
+      if (!event.eventId || event.contentHash !== sha256(event.content || '')) throw new DomainError('DATA_CORRUPT', 'Snapshot event hash does not match.', { status: 409 });
+    }
+  }
+  if (snapshot.snapshotHash !== sha256(JSON.stringify(snapshotPayload(snapshot)))) throw new DomainError('DATA_CORRUPT', 'Conversation snapshot hash does not match.', { status: 409 });
+  return snapshot;
+}
+
+class ConversationStore {
+  constructor(options = {}) {
+    this.layout = options.layout;
+    this.atomic = options.atomic || AtomicFile;
+    this.projectStore = options.projectStore || null;
+    this.logger = options.logger || null;
+  }
+
+  async log(level, event, message, context) {
+    try {
+      if (this.logger && typeof this.logger[level] === 'function') await this.logger[level](event, message, context);
+    } catch {
+      // Conversation durability is independent from observer failures.
+    }
+  }
+
+  readEvents(projectId) {
+    validateProjectId(projectId);
+    return readJsonlStrict(
+      this.layout.getProjectConversationEventsPath(projectId),
+      event => validateConversationEvent(event, projectId),
+      'Conversation events',
+    );
+  }
+
+  async appendEvent(projectId, input) {
+    const event = normalizeConversationEvent(projectId, input);
+    const filePath = this.layout.getProjectConversationEventsPath(projectId);
+    const result = await this.atomic.withFileLock(`${filePath}.append.lock`, async () => {
+      const existing = this.readEvents(projectId).find(candidate => candidate.eventId === event.eventId);
+      if (existing) {
+        if (sha256(JSON.stringify(existing)) !== sha256(JSON.stringify(event))) {
+          throw new DomainError('DATA_CORRUPT', 'Duplicate conversation eventId has different content.', { status: 409 });
+        }
+        return { event: existing, appended: false };
+      }
+      appendJsonlDurable(filePath, event);
+      return { event, appended: true };
+    });
+    await this.log('info', result.appended ? 'conversation.event_appended' : 'conversation.event_deduplicated', 'Conversation event persisted.', {
+      projectId,
+      component: 'conversation-store',
+      context: {
+        eventId: event.eventId,
+        sequence: event.sequence,
+        source: event.source,
+        eventType: event.eventType,
+        role: event.role,
+        contentHash: event.contentHash,
+        contentLength: event.content.length,
+      },
+    });
+    return result;
+  }
+
+  _projectWorkspaceId(projectId) {
+    try {
+      const config = this.projectStore && typeof this.projectStore.readConfig === 'function'
+        ? this.projectStore.readConfig(projectId)
+        : null;
+      const identity = config && config.repoIdentity;
+      return identity && typeof identity === 'object' && typeof identity.workspaceId === 'string'
+        ? identity.workspaceId
+        : null;
+    } catch (_) {
+      return null;
+    }
+  }
+
+  /**
+   * Project-scoped projection of a canonical Bridge journal event. The global
+   * eventId / sequence / turnId / repoIdentity are preserved verbatim; a new
+   * local sequence is never assigned; dedup is by eventId with DATA_CORRUPT on
+   * content drift; an exact event whose workspaceId differs from the project's
+   * canonical workspace is rejected instead of contaminating the store.
+   */
+  async appendBridgeEvent(projectId, bridgeEvent) {
+    if (!bridgeEvent || typeof bridgeEvent !== 'object' || bridgeEvent.schema !== SCHEMAS.aiCodingEvent) {
+      throw new DomainError('SCHEMA_UNSUPPORTED', 'Bridge conversation event must use ai-coding-event/v1.', { status: 409 });
+    }
+    if (bridgeEvent.eventType !== 'user_prompt' && bridgeEvent.eventType !== 'assistant_response') {
+      throw new DomainError('INVALID_ARGUMENT', 'Bridge conversation event must be a user_prompt or assistant_response.');
+    }
+    if (!bridgeEvent.eventId || typeof bridgeEvent.eventId !== 'string') {
+      throw new DomainError('INVALID_ARGUMENT', 'Bridge eventId is required.');
+    }
+    if (!Number.isInteger(bridgeEvent.sequence) || bridgeEvent.sequence < 0) {
+      throw new DomainError('INVALID_ARGUMENT', 'Bridge sequence is required for projected events.');
+    }
+    const configWorkspaceId = this._projectWorkspaceId(projectId);
+    const eventIdentity = bridgeEvent.repoIdentity;
+    const eventWorkspaceId = eventIdentity && typeof eventIdentity === 'object' && typeof eventIdentity.workspaceId === 'string'
+      ? eventIdentity.workspaceId
+      : null;
+    if (configWorkspaceId && eventWorkspaceId && configWorkspaceId !== eventWorkspaceId) {
+      throw new DomainError('DATA_CORRUPT', 'Bridge event workspaceId does not match the project workspace.', { status: 409 });
+    }
+    return this.appendEvent(projectId, {
+      eventId: bridgeEvent.eventId,
+      sequence: bridgeEvent.sequence,
+      journalId: bridgeEvent.journalId,
+      source: bridgeEvent.source,
+      eventType: bridgeEvent.eventType,
+      role: bridgeEvent.role,
+      content: bridgeEvent.content == null ? '' : bridgeEvent.content,
+      sessionId: bridgeEvent.sessionId,
+      turnId: bridgeEvent.turnId,
+      projectPath: bridgeEvent.projectPath,
+      repoIdentity: eventIdentity,
+      branch: bridgeEvent.branch,
+      headAtCapture: bridgeEvent.headAtCapture,
+      capturedAt: bridgeEvent.capturedAt,
+      rawEventType: bridgeEvent.rawEventType,
+      identityConfidence: bridgeEvent.identityConfidence,
+      captureStatus: bridgeEvent.captureStatus,
+    });
+  }
+
+  legacyRequirementToEvent(projectId, requirement) {
+    if (!requirement || requirement.schema !== SCHEMAS.requirement || requirement.projectId !== projectId || !requirement.id) {
+      throw new DomainError('INVALID_ARGUMENT', 'Legacy requirement record is invalid.');
+    }
+    const source = requirement.client === 'claude' ? 'claude-code' : requirement.client;
+    return normalizeConversationEvent(projectId, {
+      eventId: `legacy-${requirement.id}`,
+      sequence: null,
+      source: SOURCES.has(source) ? source : 'codex',
+      eventType: 'user_prompt',
+      role: 'user',
+      content: requirement.requirement,
+      sessionId: requirement.sessionId,
+      turnId: `legacy-${requirement.id}`,
+      projectPath: requirement.repoPath,
+      repoIdentity: requirement.repoIdentity || null,
+      branch: requirement.branch,
+      headAtCapture: requirement.headAtRecord,
+      capturedAt: requirement.ts,
+      rawEventType: 'legacy-requirement',
+      identityConfidence: requirement.explicitCommit ? 'explicit' : 'legacy',
+      captureStatus: 'legacy-explicit-adapter',
+      explicitCommitSha: requirement.explicitCommit,
+      legacyRequirementId: requirement.id,
+    });
+  }
+
+  async importLegacyRequirements(projectId, records = null) {
+    const requirements = records || (this.projectStore ? this.projectStore.readRequirements(projectId) : []);
+    const results = [];
+    for (const requirement of requirements) results.push(await this.appendEvent(projectId, this.legacyRequirementToEvent(projectId, requirement)));
+    return results;
+  }
+
+  writeBoundary(projectId, boundaryInput) {
+    const commitSha = this.layout.validateCommitSha(boundaryInput.commitSha);
+    const boundary = validateBoundary({
+      schema: SCHEMAS.gitCommitBoundary,
+      projectId,
+      repoIdentity: boundaryInput.repoIdentity || null,
+      commitSha,
+      parentShas: Array.isArray(boundaryInput.parentShas) ? boundaryInput.parentShas.map(value => String(value).toLowerCase()) : [],
+      branch: optionalString(boundaryInput.branch),
+      committedAt: boundaryInput.committedAt || new Date().toISOString(),
+      bridgeCursorAtCommit: Number(boundaryInput.bridgeCursorAtCommit),
+      openTurnIdsAtCommit: Array.isArray(boundaryInput.openTurnIdsAtCommit) ? [...new Set(boundaryInput.openTurnIdsAtCommit.map(String))] : [],
+      operationId: String(boundaryInput.operationId || ''),
+      journalSequence: Number.isInteger(boundaryInput.journalSequence) ? boundaryInput.journalSequence : Number(boundaryInput.bridgeCursorAtCommit),
+      journalId: optionalString(boundaryInput.journalId) || 'global',
+      boundaryHash: '',
+    }, projectId, commitSha);
+    boundary.boundaryHash = sha256(JSON.stringify({ ...boundary, boundaryHash: undefined }));
+    const filePath = this.layout.getProjectCommitBoundaryPath(projectId, commitSha);
+    if (fs.existsSync(filePath)) {
+      const existing = this.readBoundary(projectId, commitSha);
+      if (existing.boundaryHash !== boundary.boundaryHash) throw new DomainError('DATA_CORRUPT', 'Conflicting evidence was supplied for an existing commit boundary.', { status: 409 });
+      return existing;
+    }
+    this.atomic.writeJsonAtomic(filePath, boundary);
+    return boundary;
+  }
+
+  readBoundary(projectId, commitSha) {
+    const normalizedSha = this.layout.validateCommitSha(commitSha);
+    return this.atomic.readJsonStrict(this.layout.getProjectCommitBoundaryPath(projectId, normalizedSha), {
+      category: 'git-commit-boundary',
+      validate: value => validateBoundary(value, projectId, normalizedSha),
+    });
+  }
+
+  listBoundaries(projectId) {
+    validateProjectId(projectId);
+    const directory = this.layout.getProjectCommitBoundariesDir(projectId);
+    if (!fs.existsSync(directory)) return [];
+    return fs.readdirSync(directory, { withFileTypes: true })
+      .filter(entry => entry.isFile() && /^[a-f0-9]{7,64}\.json$/i.test(entry.name))
+      .map(entry => this.readBoundary(projectId, entry.name.slice(0, -5)));
+  }
+
+  writeSnapshot(projectId, input) {
+    const commitSha = this.layout.validateCommitSha(input.commitSha);
+    const snapshot = {
+      schema: SCHEMAS.commitConversationSnapshot,
+      projectId,
+      repoIdentity: input.repoIdentity || null,
+      commitSha,
+      parentSha: input.parentSha || null,
+      boundaryStartCursor: input.boundaryStartCursor == null ? null : Number(input.boundaryStartCursor),
+      boundaryEndCursor: input.boundaryEndCursor == null ? null : Number(input.boundaryEndCursor),
+      status: input.status,
+      turns: input.turns || [],
+      excludedFuturePromptCount: Number(input.excludedFuturePromptCount || 0),
+      finalizedAt: input.finalizedAt || new Date().toISOString(),
+      snapshotHash: '',
+    };
+    snapshot.snapshotHash = sha256(JSON.stringify(snapshotPayload(snapshot)));
+    validateSnapshot(snapshot, projectId, commitSha);
+    const filePath = this.layout.getProjectCommitConversationPath(projectId, commitSha);
+    if (fs.existsSync(filePath)) {
+      const existing = this.readSnapshot(projectId, commitSha);
+      if (existing.snapshotHash !== snapshot.snapshotHash) throw new DomainError('IMMUTABLE_FIELD', 'Commit conversation snapshot is already frozen.', { status: 409 });
+      return existing;
+    }
+    this.atomic.writeJsonAtomic(filePath, snapshot);
+    return snapshot;
+  }
+
+  readSnapshot(projectId, commitSha) {
+    const normalizedSha = this.layout.validateCommitSha(commitSha);
+    return this.atomic.readJsonStrict(this.layout.getProjectCommitConversationPath(projectId, normalizedSha), {
+      category: 'commit-conversation-snapshot',
+      validate: value => validateSnapshot(value, projectId, normalizedSha),
+    });
+  }
+
+  listSnapshots(projectId) {
+    validateProjectId(projectId);
+    const directory = this.layout.getProjectCommitConversationsDir(projectId);
+    if (!fs.existsSync(directory)) return [];
+    return fs.readdirSync(directory, { withFileTypes: true })
+      .filter(entry => entry.isFile() && /^[a-f0-9]{7,64}\.json$/i.test(entry.name))
+      .map(entry => this.readSnapshot(projectId, entry.name.slice(0, -5)));
+  }
+}
+
+module.exports = {
+  ConversationStore,
+  SOURCES,
+  SNAPSHOT_STATUSES,
+  BINDING_KINDS,
+  sha256,
+  normalizeConversationEvent,
+  validateConversationEvent,
+  validateBoundary,
+  validateSnapshot,
+};

package/_modules/knowledge-engine/src/runtime/evidence-bundle.js

@@ -0,0 +1,228 @@
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const AtomicFile = require('./atomic-file');
+const { DomainError } = require('./contracts');
+
+const PATCH_MANIFEST_SCHEMA = 'patch-evidence-manifest/v1';
+const COMMIT_EVIDENCE_SCHEMA = 'commit-evidence-bundle/v1';
+const DEFAULT_CHUNK_BYTES = 512 * 1024;
+
+function hashBuffer(value) {
+  return `sha256:${crypto.createHash('sha256').update(value).digest('hex')}`;
+}
+
+function manifestPayload(manifest) {
+  const { manifestHash, ...payload } = manifest;
+  return payload;
+}
+
+function lineSafeChunks(buffer, maxChunkBytes = DEFAULT_CHUNK_BYTES) {
+  const limit = Math.max(64 * 1024, Number(maxChunkBytes || DEFAULT_CHUNK_BYTES));
+  const chunks = [];
+  let start = 0;
+  while (start < buffer.length) {
+    let end = Math.min(buffer.length, start + limit);
+    if (end < buffer.length) {
+      const previousNewline = buffer.lastIndexOf(0x0a, end - 1);
+      if (previousNewline >= start) end = previousNewline + 1;
+      else {
+        const nextNewline = buffer.indexOf(0x0a, end);
+        end = nextNewline === -1 ? buffer.length : nextNewline + 1;
+      }
+    }
+    if (end <= start) end = buffer.length;
+    chunks.push(buffer.subarray(start, end));
+    start = end;
+  }
+  if (!chunks.length) chunks.push(Buffer.alloc(0));
+  return chunks;
+}
+
+function chunkMetadata(buffer, inheritedSourcePaths = []) {
+  const text = buffer.toString('utf8');
+  const sourcePaths = [...inheritedSourcePaths];
+  const hunks = [];
+  for (const line of text.split('\n')) {
+    const diff = line.match(/^diff --git a\/(.+) b\/(.+)$/);
+    if (diff) {
+      sourcePaths.push(diff[1], diff[2]);
+      continue;
+    }
+    if (line.startsWith('@@')) hunks.push(line.slice(0, 512));
+  }
+  return {
+    sourcePaths: [...new Set(sourcePaths)],
+    hunkHeaders: hunks,
+  };
+}
+
+function readManifestStrict(manifestPath, atomic = AtomicFile) {
+  return atomic.readJsonStrict(manifestPath, {
+    category: 'patch-evidence-manifest',
+    validate: manifest => {
+      if (!manifest || manifest.schema !== PATCH_MANIFEST_SCHEMA || !Array.isArray(manifest.chunks)
+        || !manifest.fullPatchHash || !Number.isInteger(manifest.totalBytes) || manifest.totalBytes < 0
+        || manifest.chunkCount !== manifest.chunks.length) {
+        throw new DomainError('EVIDENCE_INTEGRITY_FAILED', 'Patch evidence manifest is invalid.', { status: 500 });
+      }
+      if (manifest.manifestHash !== hashBuffer(Buffer.from(JSON.stringify(manifestPayload(manifest)), 'utf8'))) {
+        throw new DomainError('EVIDENCE_INTEGRITY_FAILED', 'Patch evidence manifest hash does not match.', { status: 500 });
+      }
+      return manifest;
+    },
+  });
+}
+
+function safeChunkPath(evidenceRoot, relativePath) {
+  if (!/^patches\/\d{6}\.patch$/.test(String(relativePath || ''))) {
+    throw new DomainError('EVIDENCE_INTEGRITY_FAILED', 'Patch evidence chunk path is invalid.', { status: 500 });
+  }
+  const root = path.resolve(evidenceRoot);
+  const target = path.resolve(root, ...relativePath.split('/'));
+  const relative = path.relative(root, target);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new DomainError('EVIDENCE_INTEGRITY_FAILED', 'Patch evidence chunk escapes its read-only root.', { status: 500 });
+  }
+  return target;
+}
+
+class ExactPatchEvidenceBundle {
+  constructor(options = {}) {
+    this.atomic = options.atomic || AtomicFile;
+    this.maxChunkBytes = Number(options.maxChunkBytes || DEFAULT_CHUNK_BYTES);
+  }
+
+  build(input = {}) {
+    const evidenceRoot = path.resolve(String(input.evidenceRoot || ''));
+    if (!input.evidenceRoot) throw new DomainError('EVIDENCE_INTEGRITY_FAILED', 'Patch evidence root is required.', { status: 500 });
+    const patch = Buffer.isBuffer(input.patch) ? input.patch : Buffer.from(String(input.patch || ''), 'utf8');
+    const fullPatchHash = hashBuffer(patch);
+    if (input.patchHash && input.patchHash !== fullPatchHash) {
+      throw new DomainError('EVIDENCE_INTEGRITY_FAILED', 'Full patch hash changed before evidence bundling.', { status: 500 });
+    }
+    const manifestPath = path.join(evidenceRoot, 'patch-manifest.json');
+    if (fs.existsSync(manifestPath)) {
+      const manifest = this.verify(evidenceRoot, { expectedPatchHash: fullPatchHash, expectedBytes: patch.length });
+      return this.describe(evidenceRoot, manifest);
+    }
+
+    fs.mkdirSync(path.join(evidenceRoot, 'patches'), { recursive: true });
+    const chunks = lineSafeChunks(patch, this.maxChunkBytes);
+    let activeSourcePaths = [];
+    const records = chunks.map((chunk, index) => {
+      const relativePath = `patches/${String(index + 1).padStart(6, '0')}.patch`;
+      const filePath = safeChunkPath(evidenceRoot, relativePath);
+      this.atomic.writeFileAtomic(filePath, chunk);
+      const metadata = chunkMetadata(chunk, activeSourcePaths);
+      if (metadata.sourcePaths.length) activeSourcePaths = metadata.sourcePaths.slice(-2);
+      return {
+        sequence: index + 1,
+        path: relativePath,
+        bytes: chunk.length,
+        sha256: hashBuffer(chunk),
+        ...metadata,
+      };
+    });
+    const manifest = {
+      schema: PATCH_MANIFEST_SCHEMA,
+      fullPatchHash,
+      totalBytes: patch.length,
+      chunkCount: records.length,
+      chunks: records,
+      manifestHash: '',
+    };
+    manifest.manifestHash = hashBuffer(Buffer.from(JSON.stringify(manifestPayload(manifest)), 'utf8'));
+    this.atomic.writeJsonAtomic(manifestPath, manifest);
+    const commitEvidence = {
+      schema: COMMIT_EVIDENCE_SCHEMA,
+      commit: input.commit || {},
+      files: input.files || [],
+      fullPatchHash,
+      totalBytes: patch.length,
+      patchManifestHash: manifest.manifestHash,
+    };
+    this.atomic.writeJsonAtomic(path.join(evidenceRoot, 'commit.json'), commitEvidence);
+    this.verify(evidenceRoot, { expectedPatchHash: fullPatchHash, expectedBytes: patch.length });
+    return this.describe(evidenceRoot, manifest);
+  }
+
+  verify(evidenceRoot, expected = {}) {
+    try {
+      return this.verifyUnchecked(evidenceRoot, expected);
+    } catch (error) {
+      if (error && error.code === 'EVIDENCE_INTEGRITY_FAILED') throw error;
+      throw new DomainError('EVIDENCE_INTEGRITY_FAILED', 'Patch evidence bundle could not be read or verified.', {
+        status: 500,
+        cause: error,
+        retryable: true,
+      });
+    }
+  }
+
+  verifyUnchecked(evidenceRoot, expected = {}) {
+    const root = path.resolve(evidenceRoot);
+    const manifest = readManifestStrict(path.join(root, 'patch-manifest.json'), this.atomic);
+    const commitEvidence = this.atomic.readJsonStrict(path.join(root, 'commit.json'), {
+      category: 'commit-evidence-bundle',
+      validate: value => {
+        if (!value || value.schema !== COMMIT_EVIDENCE_SCHEMA || value.fullPatchHash !== manifest.fullPatchHash
+          || value.totalBytes !== manifest.totalBytes || value.patchManifestHash !== manifest.manifestHash
+          || !value.commit || !Array.isArray(value.files)) {
+          throw new DomainError('EVIDENCE_INTEGRITY_FAILED', 'Commit evidence metadata does not match the patch manifest.', { status: 500 });
+        }
+        return value;
+      },
+    });
+    if (expected.expectedPatchHash && manifest.fullPatchHash !== expected.expectedPatchHash) {
+      throw new DomainError('EVIDENCE_INTEGRITY_FAILED', 'Frozen patch evidence hash does not match the claim.', { status: 500 });
+    }
+    if (expected.expectedBytes != null && manifest.totalBytes !== expected.expectedBytes) {
+      throw new DomainError('EVIDENCE_INTEGRITY_FAILED', 'Frozen patch evidence byte count does not match the claim.', { status: 500 });
+    }
+    const aggregate = crypto.createHash('sha256');
+    let bytes = 0;
+    manifest.chunks.forEach((chunk, index) => {
+      if (chunk.sequence !== index + 1 || !Number.isInteger(chunk.bytes) || chunk.bytes < 0 || !chunk.sha256) {
+        throw new DomainError('EVIDENCE_INTEGRITY_FAILED', 'Patch evidence chunk order or metadata is invalid.', { status: 500 });
+      }
+      const filePath = safeChunkPath(root, chunk.path);
+      if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile() || fs.lstatSync(filePath).isSymbolicLink()) {
+        throw new DomainError('EVIDENCE_INTEGRITY_FAILED', 'Patch evidence chunk is missing or unsafe.', { status: 500 });
+      }
+      const value = fs.readFileSync(filePath);
+      if (value.length !== chunk.bytes || hashBuffer(value) !== chunk.sha256) {
+        throw new DomainError('EVIDENCE_INTEGRITY_FAILED', 'Patch evidence chunk failed integrity validation.', { status: 500 });
+      }
+      aggregate.update(value);
+      bytes += value.length;
+    });
+    if (bytes !== manifest.totalBytes || `sha256:${aggregate.digest('hex')}` !== manifest.fullPatchHash) {
+      throw new DomainError('EVIDENCE_INTEGRITY_FAILED', 'Patch evidence chunks do not exactly cover the full diff.', { status: 500 });
+    }
+    void commitEvidence;
+    return manifest;
+  }
+
+  describe(evidenceRoot, manifest) {
+    return {
+      root: path.resolve(evidenceRoot),
+      commitPath: path.join(path.resolve(evidenceRoot), 'commit.json'),
+      manifestPath: path.join(path.resolve(evidenceRoot), 'patch-manifest.json'),
+      manifestHash: manifest.manifestHash,
+      chunkCount: manifest.chunkCount,
+      totalBytes: manifest.totalBytes,
+      chunkBytes: manifest.chunks.map(chunk => chunk.bytes),
+    };
+  }
+}
+
+module.exports = {
+  PATCH_MANIFEST_SCHEMA,
+  COMMIT_EVIDENCE_SCHEMA,
+  DEFAULT_CHUNK_BYTES,
+  ExactPatchEvidenceBundle,
+  hashBuffer,
+  lineSafeChunks,
+  readManifestStrict,
+};

package/_modules/knowledge-engine/src/runtime/git-runner.js

@@ -0,0 +1,62 @@
+// Shared git runner used by server.js, context-pack-builder.js, and tests.
+// Wraps spawn() with a hard timeout and returns { ok, code, stdout, stderr, error }.
+
+const { spawn } = require('child_process');
+const fs = require('fs');
+
+function execGit(cwd, args, timeoutMs = 8000) {
+  return new Promise((resolve) => {
+    if (!cwd || !fs.existsSync(cwd)) {
+      return resolve({ ok: false, code: -1, stdout: '', stderr: 'missing path', error: 'missing path' });
+    }
+    const child = spawn('git', args, { cwd, windowsHide: true, timeout: timeoutMs });
+    const outChunks = [];
+    const errChunks = [];
+    child.stdout.on('data', d => outChunks.push(Buffer.from(d)));
+    child.stderr.on('data', d => errChunks.push(Buffer.from(d)));
+    let timedOut = false;
+    const killer = setTimeout(() => { timedOut = true; child.kill(); }, timeoutMs);
+    child.on('error', e => {
+      clearTimeout(killer);
+      const stdoutBuffer = Buffer.concat(outChunks);
+      const stderrBuffer = Buffer.concat(errChunks);
+      resolve({ ok: false, code: -1, stdout: stdoutBuffer.toString('utf8'), stdoutBuffer, stderr: stderrBuffer.toString('utf8'), stderrBuffer, error: e.message });
+    });
+    child.on('close', code => {
+      clearTimeout(killer);
+      const stdoutBuffer = Buffer.concat(outChunks);
+      const stderrBuffer = Buffer.concat(errChunks);
+      resolve({ ok: code === 0 && !timedOut, code, stdout: stdoutBuffer.toString('utf8'), stdoutBuffer, stderr: stderrBuffer.toString('utf8'), stderrBuffer, error: timedOut ? 'timeout' : null });
+    });
+  });
+}
+
+let _cachedGitVersion = null;
+async function getGitVersion() {
+  if (_cachedGitVersion !== null) return _cachedGitVersion;
+  try {
+    const r = await execGit(process.cwd(), ['--version'], 5000);
+    if (!r || !r.ok) {
+      return _cachedGitVersion = { ok: false, major: 0, minor: 0, raw: '' };
+    }
+    const raw = String(r.stdout || '').trim();
+    const m = raw.match(/(\d+)\.(\d+)/);
+    if (!m) return _cachedGitVersion = { ok: false, major: 0, minor: 0, raw };
+    return _cachedGitVersion = { ok: true, major: Number(m[1]), minor: Number(m[2]), raw };
+  } catch (_) {
+    return _cachedGitVersion = { ok: false, major: 0, minor: 0, raw: '' };
+  }
+}
+function _resetGitVersionCache() {
+  _cachedGitVersion = null;
+}
+
+function _setGitVersionForTests(value) {
+  if (value === null || value === undefined) {
+    _cachedGitVersion = null;
+    return;
+  }
+  _cachedGitVersion = value;
+}
+
+module.exports = { execGit, getGitVersion, _resetGitVersionCache, _setGitVersionForTests };