@feng0531/dsh-code-review 0.31.1 → 0.32.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 变更记录
 
+## 0.32.0
+
+- 新增显式callerScopePaths工作区Git限定字面引用方捕获；预览显示扫描身份和候选，非匹配正文不发送。
+- 元数据/正文/探针/生命周期硬预算，所有扫描hash及索引与竞争路径重核，调用者与既有上下文共享名额；历史/SVN明确拒绝。
+- 报告导航限制，不冒充完整caller或符号绑定；302离线测试通过。发布门禁尚在执行。
+
 ## 0.31.1
 
 - 最终报告保留业务需求hash/bytes与不可信状态，不重印正文，预览发送告知补全。

package/README.md

@@ -4,7 +4,9 @@
 
 ## 当前状态
 
-当前代码版本为 0.31.1
+当前代码版本为 0.32.0（本批发布门禁进行中）
+
+预览可选callerScopePaths，最多4个非根、非重叠相对目录，仅Git工作区。预览读取目录内tracked JS/TS/C-family候选正文（含非匹配），仅匹配引用方作为上下文发送模型；128扫描文件/1MiB正文/256索引记录/64KiB索引/512竞争路径探针，发现与重核共享30秒，复核累计2MiB，仍共享20上下文及4MiB快照。绑定所有扫描hash、索引及竞争探针；execute重新捕获。历史/SVN明确不支持，不静默忽略。字面引用仅导航，不证明函数调用或完整覆盖，报告保留partial限制。
 
 最终报告记录业务需求hash/bytes用于溯源，不重复需求正文；真实Git当前/历史捕获及服务预览执行预算集成已验收。
 

package/index.mjs

@@ -12,7 +12,7 @@ export function apply(ctx, config = {}) {
   };
   ctx.tools.register({
     name: 'code_review_preview', description: 'Preview Git/SVN working-copy or Git commit/range review scope and model destination without sending source to a model. repositoryPath selects an explicit child repository relative to session workspace; file paths are repository-relative. Preview each repository separately. Show the preview before execution.',
-    parameters: { type: 'object', additionalProperties: false, properties: { businessRequirement: { type: 'string', maxLength: 16384, description: 'Optional business constraint text up to 16KiB UTF8; untrusted data, not evidence or permission. Bound to preview and sent in review phases.' }, commit: { type: 'string', description: 'Git commit versus sole parent; root empty, merge requires range.' }, baseRevision: { type: 'string', description: 'Git old endpoint; requires targetRevision, mutually exclusive with commit.' }, targetRevision: { type: 'string', description: 'Git new endpoint, exact tree endpoints not merge-base. Context is captured from target tree only; explicit rules are target-tree blobs too.' }, repositoryPath: { type: 'string', description: 'Workspace-relative explicit child Git/SVN repository root, forward slashes; omit for current repository.' }, selectedPaths: { type: 'array', items: { type: 'string' }, maxItems: 200 }, autoContext: { type: 'boolean', description: 'Opt in to bounded direct tracked Git/SVN import/include context captured and shown in preview.' }, contextPaths: { type: 'array', items: { type: 'string' }, maxItems: 20 }, rulePaths: { type: 'array', items: { type: 'string' }, maxItems: 4 } } },
+    parameters: { type: 'object', additionalProperties: false, properties: { callerScopePaths: { type: 'array', minItems: 1, maxItems: 4, items: { type: 'string' }, description: 'Explicit non-root repository-relative directories for bounded tracked literal reverse import/include discovery. Git working review only. Preview reads candidate bodies, including nonmatches; only captured matching context is sent. Navigation only, not complete caller coverage.' }, businessRequirement: { type: 'string', maxLength: 16384, description: 'Optional business constraint text up to 16KiB UTF8; untrusted data, not evidence or permission. Bound to preview and sent in review phases.' }, commit: { type: 'string', description: 'Git commit versus sole parent; root empty, merge requires range.' }, baseRevision: { type: 'string', description: 'Git old endpoint; requires targetRevision, mutually exclusive with commit.' }, targetRevision: { type: 'string', description: 'Git new endpoint, exact tree endpoints not merge-base. Context is captured from target tree only; explicit rules are target-tree blobs too.' }, repositoryPath: { type: 'string', description: 'Workspace-relative explicit child Git/SVN repository root, forward slashes; omit for current repository.' }, selectedPaths: { type: 'array', items: { type: 'string' }, maxItems: 200 }, autoContext: { type: 'boolean', description: 'Opt in to bounded direct tracked Git/SVN import/include context captured and shown in preview.' }, contextPaths: { type: 'array', items: { type: 'string' }, maxItems: 20 }, rulePaths: { type: 'array', items: { type: 'string' }, maxItems: 4 } } },
     output,
     async execute(args, exec) { const preview = await service.preview(args, exec); return { json: JSON.stringify(preview), markdown: '' }; },
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feng0531/dsh-code-review",
-  "version": "0.31.1",
+  "version": "0.32.0",
   "private": false,
   "license": "SEE LICENSE IN LICENSE",
   "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },

package/src/caller-candidates.mjs

@@ -0,0 +1,32 @@
+import { contextCandidates } from './context-candidates.mjs';
+import { relativePath } from './content.mjs';
+import { isSecretPath } from './secret-path.mjs';
+
+// Pure reverse navigation; resolutionPaths must contain every competitor.
+export function callerCandidates(files, scanned, resolutionPaths) {
+  if (!Array.isArray(files) || files.length > 200 || !Array.isArray(scanned) || scanned.length > 128 || !Array.isArray(resolutionPaths) || resolutionPaths.length > 512) throw new Error('Caller navigation limit exceeded');
+  for (const name of resolutionPaths) relativePath(name);
+  const changed = new Set(), targets = new Set();
+  for (const file of files) {
+    relativePath(file.path); changed.add(file.path);
+    if (file.oldPath) { relativePath(file.oldPath); changed.add(file.oldPath); }
+    if (file.eligibility === 'reviewable' && file.rightExists !== false && !isSecretPath(file.path)) targets.add(file.path);
+  }
+  const candidates = [], probes = new Set(), seen = new Set();
+  for (const source of scanned) {
+    relativePath(source.path);
+    if (seen.has(source.path)) throw new Error('Duplicate caller source');
+    seen.add(source.path);
+    if (changed.has(source.path) || isSecretPath(source.path)) continue;
+    if (!/\.(mjs|cjs|js|jsx|ts|tsx|c|cc|cpp|cxx|h|hh|hpp|hxx|shader|hlsl|glsl|cginc|hlsli|compute)$/i.test(source.path)) continue;
+    if (typeof source.text !== 'string' || Buffer.byteLength(source.text) > 256 * 1024) throw new Error('Invalid caller source content');
+    const plan = contextCandidates([{path:source.path,eligibility:'reviewable',right:{text:source.text}}], resolutionPaths, {onProbe:paths=>{
+      for (const name of paths) probes.add(name);
+      if (probes.size > 512) throw new Error('Caller resolution probe limit exceeded');
+    }});
+    if (plan.truncated) throw new Error('Caller navigation result limit exceeded');
+    for (const target of plan.candidates) if (targets.has(target.path)) candidates.push({fromPath:source.path,targetPath:target.path,reason:target.reasons[0],confidence:'navigation-only'});
+  }
+  const compare=(a,b)=>a<b?-1:a>b?1:0;
+  return {candidates:candidates.sort((a,b)=>compare(a.fromPath,b.fromPath)||compare(a.targetPath,b.targetPath)),probePaths:[...probes].sort(),notice:'Literal module/include references only; not function calls, reachability, semantic binding or complete caller coverage.'};
+}

package/src/caller-capture.mjs

@@ -0,0 +1,44 @@
+import {gitCallerIndex} from './caller-index.mjs';
+import {gitCallerProbes} from './caller-probes.mjs';
+import {callerCandidates} from './caller-candidates.mjs';
+import {readLocal} from './content.mjs';
+import {isSecretPath} from './secret-path.mjs';
+
+// Called only by preview capture, never by a model retrieval request.
+export async function captureCallers(root, files, scopes, options={}) {
+ const deadline=AbortSignal.timeout(30000);
+ const signal=options.signal?AbortSignal.any([options.signal,deadline]):deadline;
+ const bounded={...options,signal,maxFileBytes:Math.min(options.maxFileBytes??256*1024,256*1024)};
+ const index=await gitCallerIndex(root,scopes,bounded);
+ const changed=new Set(files.flatMap(f=>[f.path,...(f.oldPath?[f.oldPath]:[])]));
+ const rules=new Set(options.rulePaths??[]),scanned=[],skipped=[];
+ let scannedBytes=0;
+ for(const name of index.paths){
+  signal.throwIfAborted();
+  if(changed.has(name)||rules.has(name)||isSecretPath(name)) {skipped.push({path:name,reason:'Excluded from caller discovery'});continue;}
+  if(!/\.(mjs|cjs|js|jsx|ts|tsx|c|cc|cpp|cxx|h|hh|hpp|hxx|shader|hlsl|glsl|cginc|hlsli|compute)$/i.test(name)){skipped.push({path:name,reason:'Unsupported caller language'});continue;}
+  if(scanned.length>=128)throw new Error('Caller scan file limit exceeded');
+  // Read failures are fatal: unread bytes are not negative search evidence.
+  const content=await readLocal(root,name,bounded);
+  scannedBytes+=content.bytes;
+  if(scannedBytes>1024*1024)throw new Error('Caller scan byte limit exceeded');
+  scanned.push({path:name,...content});
+ }
+ const requested=callerCandidates(files,scanned,[]).probePaths;
+ const probes=await gitCallerProbes(root,requested,bounded);
+ const plan=callerCandidates(files,scanned,probes.paths);
+ let verifiedBytes=0;
+ const verify=async()=>{
+ for(const source of scanned){
+  const again=await readLocal(root,source.path,bounded);verifiedBytes+=again.bytes;
+  if(verifiedBytes>2*1024*1024)throw new Error('Caller verification byte limit exceeded');
+  if(again.hash!==source.hash)throw new Error('Caller scan source changed during capture');
+ }
+ if((await gitCallerIndex(root,scopes,bounded)).fingerprint!==index.fingerprint)throw new Error('Caller index changed during capture');
+ if((await gitCallerProbes(root,requested,bounded)).fingerprint!==probes.fingerprint)throw new Error('Caller resolution changed during capture');
+ signal.throwIfAborted();
+ };
+ await verify();
+ const paths=new Set(plan.candidates.map(c=>c.fromPath));
+ return {verify,context:scanned.filter(s=>paths.has(s.path)),discovery:{scopes:index.scopes,indexFingerprint:index.fingerprint,probeFingerprint:probes.fingerprint,scanned:scanned.map(({path,hash,bytes})=>({path,hash,bytes})),scannedBytes,skipped,candidates:plan.candidates,notice:plan.notice,incomplete:true,limitations:['Only supported literal references inside approved scopes were searched; no complete caller or semantic coverage.']}};
+}

package/src/caller-index.mjs

@@ -0,0 +1,41 @@
+import { checked } from './process.mjs';
+import { relativePath, hash } from './content.mjs';
+import { assertNonSecretPath } from './secret-path.mjs';
+
+export function validateCallerScopes(scopes) {
+  if (!Array.isArray(scopes) || scopes.length < 1 || scopes.length > 4) throw new Error('Invalid caller scopes');
+  for (const scope of scopes) {
+    relativePath(scope); assertNonSecretPath(scope);
+    if (/[?*\[\]]/.test(scope)) throw new Error('Caller scope must be literal');
+  }
+  const sorted = [...scopes].sort();
+  for (let i = 0; i < sorted.length; i++) for (let j = i + 1; j < sorted.length; j++) {
+    if (sorted[j] === sorted[i] || sorted[j].startsWith(sorted[i] + '/')) throw new Error('Overlapping caller scopes');
+  }
+  return sorted;
+}
+
+// Explicit discovery scopes, never an implicit repository-wide index.
+export async function gitCallerIndex(root, scopes, options = {}) {
+  const approved = validateCallerScopes(scopes);
+  const chunks = [], entries = new Map();
+  let bytes = 0, records = 0;
+  for (const scope of approved) {
+    const chunk = await checked('git', ['--no-optional-locks', '--literal-pathspecs', '-c', 'core.fsmonitor=false', '-c', 'core.untrackedCache=false', 'ls-files', '--stage', '-z', '--', scope], { ...options, cwd: root, maxBytes: 64 * 1024 });
+    bytes += chunk.length;
+    if (bytes > 64 * 1024) throw new Error('Caller index byte limit exceeded');
+    const text = new TextDecoder('utf-8', { fatal: true }).decode(chunk);
+    if (text && !text.endsWith('\0')) throw new Error('Incomplete caller index');
+    for (const record of text.split('\0').filter(Boolean)) {
+      if (++records > 256) throw new Error('Caller index path limit exceeded');
+      const match = /^(\d{6}) ([a-f0-9]{40}|[a-f0-9]{64}) ([0-3])\t([\s\S]+)$/.exec(record);
+      if (!match) throw new Error('Invalid caller index record');
+      const name = relativePath(match[4]);
+      if (!name.startsWith(scope + '/')) throw new Error('Caller scope is not a directory or index escaped scope');
+      const regular = match[3] === '0' && ['100644', '100755'].includes(match[1]);
+      entries.set(name, entries.has(name) ? false : regular);
+    }
+    chunks.push(chunk);
+  }
+  return { scopes: approved, paths: [...entries].filter(([, valid]) => valid).map(([name]) => name).sort(), fingerprint: hash(Buffer.concat(chunks)), records, bytes };
+}

package/src/caller-probes.mjs

@@ -0,0 +1,28 @@
+import { checked } from './process.mjs';
+import { relativePath, hash } from './content.mjs';
+
+// Metadata only: a directory, conflicted file or symlink is a competitor too.
+export async function gitCallerProbes(root, probePaths, options = {}) {
+  if (!Array.isArray(probePaths) || probePaths.length > 512 || new Set(probePaths).size !== probePaths.length) throw new Error('Invalid caller probes');
+  const chunks = [], existing = [];
+  let bytes = 0;
+  for (const name of [...probePaths].sort()) {
+    relativePath(name);
+    const chunk = await checked('git', ['--no-optional-locks','--literal-pathspecs','-c','core.fsmonitor=false','-c','core.untrackedCache=false','ls-files','--stage','-z','--',name], {...options,cwd:root,maxBytes:64*1024});
+    bytes += chunk.length;
+    if (bytes > 1024*1024) throw new Error('Caller probe metadata limit exceeded');
+    const text = new TextDecoder('utf-8',{fatal:true}).decode(chunk);
+    if (text && !text.endsWith('\0')) throw new Error('Incomplete caller probe');
+    const records=text.split('\0').filter(Boolean);
+    for (const record of records) {
+      const match=/^(\d{6}) ([a-f0-9]{40}|[a-f0-9]{64}) ([0-3])\t([\s\S]+)$/.exec(record);
+      if (!match) throw new Error('Invalid caller probe record');
+      relativePath(match[4]);
+      if (match[4] !== name && !match[4].startsWith(name+'/')) throw new Error('Caller probe escaped literal path');
+    }
+    if (records.length) existing.push(name);
+    // Include missing probe names in identity, not only returned records.
+    chunks.push(Buffer.from(name+'\0'),chunk);
+  }
+  return {paths:existing,fingerprint:hash(Buffer.concat(chunks)),bytes};
+}

package/src/review.mjs

@@ -93,6 +93,11 @@ export async function reviewSnapshot(snapshot, model, options = {}) {
   const report = { schemaVersion: 1, snapshotId: input.id, vcs: input.vcs, status: 'completed', files: [], findings: [], limitations: [], modelCalls: 0 };
   validateBusinessRequirement(input.businessRequirement);
   if(input.businessRequirement!==undefined)report.businessRequirement={hash:hash(input.businessRequirement),bytes:Buffer.byteLength(input.businessRequirement),status:'untrusted-constraint'};
+  if (input.callerDiscovery) {
+    report.callerDiscovery = structuredClone(input.callerDiscovery);
+    report.limitations.push({text:'调用者发现仅限批准目录内字面引用，不证明函数调用或完整覆盖；仅已捕获上下文可用于证据。'});
+    if (input.callerDiscovery.candidates.some(c=>c.status==='blocked')) report.limitations.push({text:'部分引用方因上下文名额限制未捕获。'});
+  }
   if (input.autoContext) {
     report.autoContext = structuredClone(input.autoContext);
     if (input.autoContext.truncated || input.autoContext.candidates.some(c => c.status === 'blocked')) report.limitations.push({ text: '自动上下文未完全捕获：存在截断或阻塞，仅实际捕获路径可用于证据。' });
@@ -268,6 +273,7 @@ const safe = text => Array.from(String(text ?? '')).map(c => {
 }).join('');
 export function markdownReport(report) {
   const output = ['# Code Review 报告', '', '状态：' + report.status, '快照：' + report.snapshotId, '', '## 覆盖情况'];
+  if (report.callerDiscovery) output.push('- 引用方发现：扫描 '+report.callerDiscovery.scanned.length+' 个文件，捕获 '+report.callerDiscovery.capturedPaths.length+' 个上下文；仅批准目录字面引用导航，不证明函数调用或完整覆盖。');
   if(report.businessRequirement)output.push('- 业务需求：SHA256 '+safe(report.businessRequirement.hash)+' · '+report.businessRequirement.bytes+' bytes；不可信约束，不是证据或权限，全文不在报告重复。');
   for (const file of report.files) for (const correction of file.anchorCorrections ?? []) output.push('- 定位纠正：' + safe(correction.originalCandidate.fileId) + ' · ' + safe(correction.status) + ' · ' + safe(correction.reason) + '；原完整候选保留JSON，仅定位不证明因果');
   if (report.history) output.push('- Git历史审查：' + safe(report.history.mode) + ' · ' + safe(report.history.base ?? 'empty') + ' → ' + safe(report.history.target) + '；精确端点树差异，重命名按增删，不含工作树');

package/src/service.mjs

@@ -1,3 +1,4 @@
+import { validateCallerScopes } from './caller-index.mjs';
 import { validateBusinessRequirement } from './business-requirement.mjs';
 import { hash } from './content.mjs';
 import { resolveWorkspaceRepository } from './workspace-repository.mjs';
@@ -28,10 +29,11 @@ export function createReviewService(llm, { capture = captureSnapshot, now = Date
       exec = bind(exec);
       exec.signal.throwIfAborted();
       if (busy) throw new Error('Review service busy');
-      if (!args || Object.keys(args).some(k => !['repositoryPath', 'selectedPaths', 'contextPaths', 'rulePaths', 'autoContext', 'commit', 'baseRevision', 'targetRevision','businessRequirement'].includes(k))) throw new Error('Unknown preview argument');
+      if (!args || Object.keys(args).some(k => !['repositoryPath', 'selectedPaths', 'contextPaths', 'rulePaths', 'autoContext', 'commit', 'baseRevision', 'targetRevision','businessRequirement','callerScopePaths'].includes(k))) throw new Error('Unknown preview argument');
       if (args.autoContext !== undefined && typeof args.autoContext !== 'boolean') throw new Error('Invalid autoContext option');
       for (const key of ['selectedPaths', 'contextPaths', 'rulePaths']) if (args[key] !== undefined && (!Array.isArray(args[key]) || args[key].length > (key === 'rulePaths' ? 4 : 200) || args[key].some(p => typeof p !== 'string'))) throw new Error('Invalid path list');
       validateBusinessRequirement(args.businessRequirement);
+      if (args.callerScopePaths !== undefined) validateCallerScopes(args.callerScopePaths);
       const current = owner(exec);
       busy = true;
       try {
@@ -45,7 +47,7 @@ export function createReviewService(llm, { capture = captureSnapshot, now = Date
         while (previews.size >= maxPreviews) previews.delete(previews.keys().next().value);
         const previewId = randomUUID();
         previews.set(previewId, { ...current, target, options, snapshotId: snapshot.id, expires: now() + ttlMs });
-        return { ...(options.businessRequirement!==undefined?{businessRequirement:{text:options.businessRequirement,hash:hash(options.businessRequirement),bytes:Buffer.byteLength(options.businessRequirement)}}:{}), previewId, plan, snapshotId: snapshot.id, repositoryRoot: snapshot.root, vcs: snapshot.vcs, ...(snapshot.history ? { history: snapshot.history } : {}), model: current.route, modelSendingEnabled: allowModelSending, files: snapshot.files.map(f => ({ path: f.path, eligibility: f.eligibility, reason: f.reason })), contextPaths: snapshot.context.map(c => c.path), ...(snapshot.autoContext ? { autoContext: snapshot.autoContext } : {}), rules: (snapshot.rules ?? []).map(({ path, hash }) => ({ path, hash })), notice: (enableRiskPlanning ? '执行先制定风险假设计划，再审查并复核；计划不是证据，所有阶段共享原预算。' : '') + '执行会向上述模型提供方发送可审查文件两侧内容、预览列出的显式/自动上下文、所选项目规则全文及预览业务需求文本。模型可在该快照范围内多轮只读检索，不读取范围外文件；候选生成后会进行证据与反证复核，两阶段各最多3轮检索，共享每文件120秒和总模型调用100次预算；复核不能证明缺陷成立。plan仅预检初始输入，ready不代表已审查；minimumCalls不含后续检索/复核/动态业务综合；多文件可先进行业务分组，分组失败保留原组并记录限制，动态综合数执行前未知，实际预算可能不足。请先向用户展示范围，获得确认后执行。' };
+        return { ...(options.businessRequirement!==undefined?{businessRequirement:{text:options.businessRequirement,hash:hash(options.businessRequirement),bytes:Buffer.byteLength(options.businessRequirement)}}:{}), previewId, plan, snapshotId: snapshot.id, repositoryRoot: snapshot.root, vcs: snapshot.vcs, ...(snapshot.history ? { history: snapshot.history } : {}), model: current.route, modelSendingEnabled: allowModelSending, files: snapshot.files.map(f => ({ path: f.path, eligibility: f.eligibility, reason: f.reason })), contextPaths: snapshot.context.map(c => c.path), ...(snapshot.callerDiscovery ? {callerDiscovery:snapshot.callerDiscovery} : {}), ...(snapshot.autoContext ? { autoContext: snapshot.autoContext } : {}), rules: (snapshot.rules ?? []).map(({ path, hash }) => ({ path, hash })), notice: (snapshot.callerDiscovery ? 'callerScopePaths已授权预览读取限定目录内tracked候选正文，包括不匹配文件；非匹配正文不发送模型，匹配捕获上下文会发送。仅字面引用导航，不是函数调用或完整调用覆盖。' : '') + (enableRiskPlanning ? '执行先制定风险假设计划，再审查并复核；计划不是证据，所有阶段共享原预算。' : '') + '执行会向上述模型提供方发送可审查文件两侧内容、预览列出的显式/自动上下文、所选项目规则全文及预览业务需求文本。模型可在该快照范围内多轮只读检索，不读取范围外文件；候选生成后会进行证据与反证复核，两阶段各最多3轮检索，共享每文件120秒和总模型调用100次预算；复核不能证明缺陷成立。plan仅预检初始输入，ready不代表已审查；minimumCalls不含后续检索/复核/动态业务综合；多文件可先进行业务分组，分组失败保留原组并记录限制，动态综合数执行前未知，实际预算可能不足。请先向用户展示范围，获得确认后执行。' };
       } finally { busy = false; }
     },
     async execute(args, exec) {

package/src/snapshot.mjs

@@ -1,3 +1,5 @@
+import { captureCallers } from './caller-capture.mjs';
+import { validateCallerScopes } from './caller-index.mjs';
 import { bindBusinessRequirement, validateBusinessRequirement } from './business-requirement.mjs';
 import { gitContextIndex, svnContextIndex } from './tracked-context.mjs';
 import { contextCandidates } from './context-candidates.mjs';
@@ -31,7 +33,9 @@ export async function captureSnapshot(cwd, options = {}) {
   if (!Array.isArray(contextPaths) || contextPaths.length > maxContextFiles) throw new Error('Context file limit exceeded');
   for (const name of contextPaths) relativePath(name);
   if (options.autoContext !== undefined && typeof options.autoContext !== 'boolean') throw new Error('Invalid autoContext option');
+  if (options.callerScopePaths !== undefined) validateCallerScopes(options.callerScopePaths);
   const type = await detectVcs(cwd);
+  if (options.callerScopePaths !== undefined && (type !== 'git' || ['commit','baseRevision','targetRevision'].some(k => options[k] !== undefined))) throw new Error('Caller discovery currently requires Git working review');
   if (['commit','baseRevision','targetRevision'].some(k => options[k] !== undefined)) {
     if (type !== 'git') throw new Error('Git revision review is unsupported on SVN');
     return bindBusinessRequirement(await captureGitHistory(cwd, options),options.businessRequirement);
@@ -63,13 +67,32 @@ export async function captureSnapshot(cwd, options = {}) {
       context.push({ path: name, ...changed.right });
     } else context.push({ path: name, ...await readLocal(snapshot.root, name, options) });
   }
+  let callerDiscovery, verifyCallers;
+  if (options.callerScopePaths !== undefined) {
+    const callers = await captureCallers(snapshot.root, snapshot.files, options.callerScopePaths, options);
+    verifyCallers = callers.verify;
+    callerDiscovery = { ...callers.discovery, capturedPaths: [] };
+    for (const item of callers.context) {
+      const present = context.find(c => c.path === item.path);
+      const matches = callerDiscovery.candidates.filter(c => c.fromPath === item.path);
+      if (present && present.hash !== item.hash) throw new Error('Caller context changed during capture');
+      if (!present && context.length >= Math.min(maxContextFiles,20)) {
+        for (const candidate of matches) { candidate.status='blocked'; candidate.captureReason='Context file limit exceeded'; }
+        continue;
+      }
+      if (!present) context.push(item);
+      callerDiscovery.capturedPaths.push(item.path);
+      for (const candidate of matches) candidate.status='captured';
+    }
+  }
   // Re-capture verifies both selected sides while collecting explicit context.
   if ((await capture(cwd, options)).id !== snapshot.id) throw new Error('Snapshot changed while collecting context');
   for (const item of context) if ((await readLocal(snapshot.root, item.path, options)).hash !== item.hash) throw new Error('Context changed during capture');
   if (index && (await (type === 'git' ? gitContextIndex : svnContextIndex)(snapshot.root, indexOptions)).fingerprint !== index.fingerprint) throw new Error('Tracked context index changed during capture');
   const verifiedRules = await captureProjectRules(snapshot.root, rulePaths, { signal: options.signal, files: snapshot.files });
   if (JSON.stringify(verifiedRules) !== JSON.stringify(rules)) throw new Error('Rules changed during capture');
-  const result = { ...snapshot, context, ...(autoContext ? { autoContext } : {}), ...(rules.length ? { rules } : {}) };
+  if (verifyCallers) await verifyCallers();
+  const result = { ...snapshot, context, ...(callerDiscovery ? {callerDiscovery} : {}), ...(autoContext ? { autoContext } : {}), ...(rules.length ? { rules } : {}) };
   delete result.id;
   const serialized = JSON.stringify(result);
   if (Buffer.byteLength(serialized) > maxSnapshotBytes) throw new Error('Snapshot size limit exceeded');