@sanqianx/project-knowledge 4.7.0 → 5.0.0

package/_site/lib/data-dir.js

@@ -1,81 +1,13 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const crypto = require('crypto');
-const { LEGACY_ASSETS, assetPath } = require('./legacy-data-manifest');
-const { isEmptyJson } = require('./data-state-classifier');
-
-let _resolved = null;
 
+let resolved = null;
 function resolveDataDirPath(options = {}) {
-  const fromEnv = options.dataDir === undefined ? process.env.KB_DATA_DIR : options.dataDir;
-  const homeDir = options.homeDir || os.homedir();
-  return path.resolve(fromEnv || path.join(homeDir, '.project-knowledge'));
+  const configured = options.dataDir === undefined ? process.env.KB_DATA_DIR : options.dataDir;
+  return path.resolve(configured || path.join(options.homeDir || os.homedir(), '.project-knowledge-v5'));
 }
 function ensureDataDir(dataDir = resolveDataDirPath()) { fs.mkdirSync(dataDir, { recursive: true }); return path.resolve(dataDir); }
-function getDataDir() { if (!_resolved) _resolved = resolveDataDirPath(); return _resolved; }
-function _resetCache() { _resolved = null; }
-function fileDigest(filePath) { return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex'); }
-function directoryDigest(root) {
-  const hash = crypto.createHash('sha256');
-  const walk = current => {
-    for (const entry of fs.readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
-      const filePath = path.join(current, entry.name);
-      const relative = path.relative(root, filePath).replace(/\\/g, '/');
-      hash.update(`${entry.isDirectory() ? 'd' : 'f'}:${relative}\0`);
-      if (entry.isDirectory()) walk(filePath); else if (entry.isFile()) hash.update(fs.readFileSync(filePath));
-    }
-  };
-  walk(root); return hash.digest('hex');
-}
-function isEmptyAsset(filePath, asset) {
-  if (!fs.existsSync(filePath)) return true;
-  if (asset.kind === 'dir') return fs.readdirSync(filePath).length === 0;
-  if (fs.statSync(filePath).size === 0) return true;
-  if (!filePath.endsWith('.json')) return false;
-  try { const raw = fs.readFileSync(filePath, 'utf8'); return isEmptyJson(JSON.parse(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw)); } catch { return false; }
-}
-function assetsEqual(source, target, asset) { return asset.kind === 'dir' ? directoryDigest(source) === directoryDigest(target) : fileDigest(source) === fileDigest(target); }
-function copyDir(source, target) {
-  fs.mkdirSync(target, { recursive: true });
-  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
-    const from = path.join(source, entry.name); const to = path.join(target, entry.name);
-    if (entry.isDirectory()) copyDir(from, to); else if (entry.isFile()) fs.copyFileSync(from, to);
-  }
-}
-
-function migrateFromLegacy({ legacyRoot, logger } = {}) {
-  if (process.env.KB_SKIP_MIGRATION === '1') return { ok: true, migrated: false, reason: 'skipped via KB_SKIP_MIGRATION=1' };
-  if (!legacyRoot || !fs.existsSync(legacyRoot)) return { ok: true, migrated: false, reason: legacyRoot ? 'legacy root does not exist' : 'no legacy root provided' };
-  const dataDir = getDataDir();
-  if (path.resolve(legacyRoot) === dataDir) return { ok: true, migrated: false, reason: 'legacy root equals data dir' };
-  // Packaged application roots may include empty scaffolding such as
-  // `projects/`. It is not user data and must never conflict with populated
-  // runtime data during startup relocation.
-  const sources = LEGACY_ASSETS.filter(asset => {
-    const source = assetPath(legacyRoot, asset);
-    return fs.existsSync(source) && !isEmptyAsset(source, asset);
-  });
-  if (!sources.length) return { ok: true, migrated: false, reason: 'no legacy assets found' };
-  const conflicts = [];
-  for (const asset of sources) {
-    const source = assetPath(legacyRoot, asset); const target = assetPath(dataDir, asset, 'target');
-    if (fs.existsSync(target) && !isEmptyAsset(target, asset) && !assetsEqual(source, target, asset)) conflicts.push(asset.target);
-  }
-  if (conflicts.length) return { ok: false, migrated: false, requiresManualRecovery: true, reason: 'legacy-data-conflict', conflicts, source: legacyRoot, target: dataDir };
-  ensureDataDir(dataDir);
-  const result = { ok: true, migrated: false, files: 0, dirs: 0, source: legacyRoot, target: dataDir };
-  try {
-    for (const asset of sources) {
-      const source = assetPath(legacyRoot, asset); const target = assetPath(dataDir, asset, 'target');
-      if (fs.existsSync(target) && assetsEqual(source, target, asset)) continue;
-      if (asset.kind === 'dir') { if (fs.existsSync(target)) fs.rmSync(target, { recursive: true, force: true }); copyDir(source, target); result.dirs++; }
-      else { fs.mkdirSync(path.dirname(target), { recursive: true }); fs.copyFileSync(source, target); result.files++; }
-    }
-    result.migrated = result.files > 0 || result.dirs > 0;
-    if (result.migrated && logger) logger(`migrated runtime data to ${dataDir} (${result.files} files, ${result.dirs} dirs from ${legacyRoot})`);
-    return result;
-  } catch (error) { return { ...result, ok: false, error: `failed to relocate legacy runtime data: ${error.message}` }; }
-}
-
-module.exports = { resolveDataDirPath, ensureDataDir, getDataDir, migrateFromLegacy, LEGACY_ASSETS, _resetCache };
+function getDataDir() { if (!resolved) resolved = resolveDataDirPath(); return resolved; }
+function _resetCache() { resolved = null; }
+module.exports = { resolveDataDirPath, ensureDataDir, getDataDir, _resetCache };

package/_site/lib/engine-connection.js

@@ -0,0 +1,67 @@
+const { DomainError } = require('./contracts');
+const { execGit } = require('./git-runner');
+
+async function connectEngine(runtime) {
+  if (runtime.analysisOwner === 'legacy' || runtime.engineConnecting) return;
+  runtime.engineConnecting = true;
+  let step = 'engine-health';
+  let projectId = '';
+  let httpStatus = 0;
+  try {
+    const bridge = runtime.moduleBridge;
+    if (bridge.engineCompatible === undefined) bridge.engineCompatible = false;
+    const headers = { 'Content-Type': 'application/json', Authorization: `Bearer ${bridge.runtimeToken}` };
+    const health = await bridge._fetch(`${bridge.engineUrl}/api/health`);
+    httpStatus = health.status;
+    if (!health.ok) throw new Error('ENGINE_UNAVAILABLE');
+    const engine = await health.json();
+    if (engine.name !== 'knowledge-engine' || engine.dataSchemaVersion !== 3) throw new Error('ENGINE_VERSION_MISMATCH');
+    step = 'runtime-authentication';
+    const auth = await bridge._fetch(`${bridge.engineUrl}/api/runtime-auth`, { headers });
+    httpStatus = auth.status;
+    if (!auth.ok) throw new Error('RUNTIME_AUTH_REQUIRED');
+    bridge.engineCompatible = true;
+    step = 'project-wiring';
+    for (const id of runtime.registryStore.listIds()) {
+      projectId = id;
+      const config = runtime.projectStore.readConfig(id);
+      const modules = await bridge.registerProjectLinks({ projectId: id, name: config.displayName, workspacePath: config.repoPath, knowledgePath: config.knowledgePath });
+      if (!modules.engine.ok || !modules.eventBridge.ok) throw new Error('PROJECT_WIRING_PENDING');
+    }
+    projectId = '';
+    step = 'runtime-configuration';
+    await bridge.syncEngineConfiguration();
+    step = 'engine-activation';
+    const activated = await bridge._fetch(`${bridge.engineUrl}/api/control`, { method: 'POST', headers, body: JSON.stringify({ enabled: true }) });
+    httpStatus = activated.status;
+    if (!activated.ok) throw new Error(activated.status === 403 ? 'RUNTIME_AUTH_REQUIRED' : 'ENGINE_ACTIVATION_FAILED');
+    runtime.ownership = { owner: 'engine', ready: true };
+  } catch (error) {
+    const codes = ['ENGINE_UNAVAILABLE', 'ENGINE_VERSION_MISMATCH', 'PROJECT_WIRING_PENDING', 'RUNTIME_AUTH_REQUIRED', 'ENGINE_ACTIVATION_FAILED'];
+    const code = codes.includes(error.message) ? error.message : 'ENGINE_CONNECTION_FAILED';
+    if (['ENGINE_VERSION_MISMATCH', 'RUNTIME_AUTH_REQUIRED'].includes(code)) runtime.moduleBridge.engineCompatible = false;
+    const messages = {
+      ENGINE_VERSION_MISMATCH: '检测到旧版知识引擎，请停止旧版服务后重新启动新版。',
+      RUNTIME_AUTH_REQUIRED: '引擎服务与外壳鉴权不一致，请停止旧版服务后重新启动新版。',
+      PROJECT_WIRING_PENDING: '项目接线未完成，请检查模块连接。',
+    };
+    const message = messages[code] || '知识引擎连接未完成，服务恢复后自动重试。';
+    const previous = runtime.ownership?.error;
+    runtime.ownership = { owner: 'engine', ready: false, message, error: { code, step, httpStatus, ...(projectId ? { projectId } : {}) } };
+    if (previous?.code !== code || previous?.step !== step || (previous?.projectId || '') !== projectId) await runtime.logger.warn('engine.connection_pending', message, { component: 'engine-connection', phase: step, projectId, context: { code, httpStatus } });
+  } finally { runtime.engineConnecting = false; }
+}
+
+async function forwardCommitToBridge(runtime, event) {
+  const config = runtime.projectStore.readConfig(event.projectId);
+  if (!runtime.layout.pathsEqual(config.repoPath, event.repoRoot) || !/^[a-f0-9]{40}$/i.test(event.head || '')) throw new DomainError('INVALID_ARGUMENT', '提交通知与项目绑定不匹配。');
+  const exists = await execGit(config.repoPath, ['cat-file', '-e', `${event.head}^{commit}`]);
+  if (!exists.ok) throw new DomainError('INVALID_ARGUMENT', '提交不属于当前仓库。');
+  const identity = await runtime.bridgeAdapter.resolveRepoIdentity(config.repoPath);
+  const result = await runtime.bridgeAdapter.appendCommitBoundary({ projectId: event.projectId, repoIdentity: identity.repoIdentity, commitSha: event.head, branch: event.branch || null, operationId: event.operationId });
+  if (result.status !== 'captured') throw new DomainError('MODULE_UNREACHABLE', '事件记录失败，请恢复事件模块后重试。', { status: 503 });
+  runtime.moduleBridge._fetch(`${runtime.moduleBridge.engineUrl}/api/bridge/notify`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}' }).catch(() => {});
+  return { journalSequence: result.boundary?.journalSequence || result.boundary?.sequence };
+}
+
+module.exports = { connectEngine, forwardCommitToBridge };

package/_site/lib/evidence-bundle.js

@@ -1,228 +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,
-};
+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,
+};