salmon-loop 0.2.3

package/dist/core/context/service.js

@@ -0,0 +1,265 @@
+import { createHash } from 'node:crypto';
+import { FileAdapter } from '../adapters/fs/file-adapter.js';
+import { defaultPathAdapter } from '../adapters/path/path-adapter.js';
+import { Pipeline } from '../grizzco/engine/pipeline/pipeline.js';
+import { getLogger } from '../observability/logger.js';
+import { CONTEXT_AUDIT_ACTION, CONTEXT_AUDIT_PHASE } from './audit-constants.js';
+import { recordContextAuditEvent } from './audit.js';
+import { IncrementalUpdater } from './cache/incremental-updater.js';
+import { MemoryContextCacheStore, } from './cache/store.js';
+import { createIntentSignature, createTargetSetSignature } from './hash.js';
+import { defaultContextServiceDeps } from './service-deps.js';
+import { buildContextBudgetStep } from './steps/context-budget.js';
+import { buildContextGatherStep } from './steps/context-gather.js';
+import { buildContextPrimaryStep } from './steps/context-primary.js';
+import { buildContextPromotionStep } from './steps/context-promotion.js';
+import { buildContextTargetsStep } from './steps/context-targets.js';
+export class ContextService {
+    deps;
+    cacheStore;
+    updaters = new Map();
+    promptCachingManager;
+    fileAdapter = new FileAdapter();
+    static MAX_CACHE_TRACKED_FILES = 64;
+    static DEFAULT_CACHE_MAX_ENTRIES = 256;
+    static DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000;
+    cacheMaxEntries;
+    cacheTtlMs;
+    cacheMetrics = {
+        hits: 0,
+        misses: 0,
+        evictions: 0,
+    };
+    constructor(deps = {}, options) {
+        this.deps = { ...defaultContextServiceDeps(), ...deps };
+        this.promptCachingManager = this.deps.promptCachingManager;
+        this.cacheMaxEntries =
+            options?.cacheMaxEntries && options.cacheMaxEntries > 0
+                ? Math.floor(options.cacheMaxEntries)
+                : ContextService.DEFAULT_CACHE_MAX_ENTRIES;
+        this.cacheTtlMs =
+            options?.cacheTtlMs && options.cacheTtlMs > 0
+                ? Math.floor(options.cacheTtlMs)
+                : ContextService.DEFAULT_CACHE_TTL_MS;
+        this.cacheStore = options?.cacheStore ?? new MemoryContextCacheStore();
+    }
+    async build(req) {
+        const diffScope = req.diffScope ?? 'primary';
+        const intentSignature = createIntentSignature({
+            instruction: req.instruction,
+            primaryFile: req.primaryFile,
+            selection: req.selection,
+            diffScope: req.diffScope,
+        });
+        const cacheKey = this.makeCacheKey(req, intentSignature);
+        const cacheLookup = await this.getValidCachedResult(cacheKey, req.repoPath);
+        recordContextAuditEvent(CONTEXT_AUDIT_ACTION.cacheLookup, {
+            cacheKey,
+            intentSignature,
+            targetSetSignature: cacheLookup.targetSetSignature,
+            hit: Boolean(cacheLookup.result),
+            missReason: cacheLookup.result ? undefined : cacheLookup.missReason,
+        }, { source: 'context', severity: 'low', scope: 'session', phase: CONTEXT_AUDIT_PHASE.primary });
+        const cached = cacheLookup.result;
+        if (cached && !req.signal?.aborted) {
+            getLogger().trace(`[CONTEXT_CACHE] hit ${cacheKey}`);
+            return cached;
+        }
+        getLogger().trace(`  [CONTEXT] Building context for repo: ${req.repoPath}`);
+        getLogger().trace(`  [CONTEXT] File: ${req.primaryFile}, Instruction: ${req.instruction}`);
+        const report = await Pipeline.of({ req, diffScope })
+            .step('CONTEXT_PRIMARY', buildContextPrimaryStep(this.deps))
+            .step('CONTEXT_GATHER', buildContextGatherStep(this.deps))
+            .step('CONTEXT_TARGETS', buildContextTargetsStep(this.deps))
+            .step('CONTEXT_PROMOTION', buildContextPromotionStep(this.deps))
+            .step('CONTEXT_BUDGET', buildContextBudgetStep(this.deps))
+            .execute();
+        if (!report.success) {
+            throw report.error ?? new Error('Context pipeline failed');
+        }
+        const contextResult = report.data;
+        const trackedFiles = this.collectTrackedFiles(req, contextResult);
+        const signature = await this.computeTrackedFilesSignature(req.repoPath, trackedFiles);
+        await this.cacheStore.set(cacheKey, {
+            result: contextResult,
+            trackedFiles,
+            signature,
+            targetSetSignature: contextResult.meta.targetSetSignature,
+            intentSignature,
+        });
+        await this.bumpCacheEntry(cacheKey);
+        await this.evictLruIfNeeded();
+        this.recordContextDiff(cacheKey, contextResult);
+        return contextResult;
+    }
+    makeCacheKey(req, intentSignature) {
+        const parts = [
+            req.repoPath,
+            req.snapshotHash ?? '',
+            req.diffScope ?? 'primary',
+            req.workspaceMode ?? 'direct',
+            intentSignature,
+        ];
+        return parts.join('::');
+    }
+    async getValidCachedResult(cacheKey, repoPath) {
+        await this.evictExpiredEntries();
+        const entry = await this.cacheStore.get(cacheKey);
+        if (!entry) {
+            this.cacheMetrics.misses += 1;
+            return { missReason: 'key_miss' };
+        }
+        if (await this.isExpired(cacheKey, entry)) {
+            this.cacheMetrics.misses += 1;
+            return { missReason: 'expired' };
+        }
+        const expectedTargetSetSignature = createTargetSetSignature(entry.result.context.targets);
+        const recordedTargetSetSignature = entry.targetSetSignature ??
+            entry.result.meta.targetSetSignature ??
+            expectedTargetSetSignature;
+        if (recordedTargetSetSignature !== expectedTargetSetSignature) {
+            await this.cacheStore.delete(cacheKey);
+            this.cacheMetrics.misses += 1;
+            return {
+                missReason: 'target_signature_mismatch',
+                targetSetSignature: expectedTargetSetSignature,
+            };
+        }
+        const nextSignature = await this.computeTrackedFilesSignature(repoPath, entry.trackedFiles);
+        if (nextSignature !== entry.signature) {
+            await this.cacheStore.delete(cacheKey);
+            this.cacheMetrics.misses += 1;
+            return { missReason: 'signature_mismatch', targetSetSignature: expectedTargetSetSignature };
+        }
+        this.cacheMetrics.hits += 1;
+        await this.bumpCacheEntry(cacheKey);
+        return { result: entry.result, targetSetSignature: expectedTargetSetSignature };
+    }
+    collectTrackedFiles(req, result) {
+        const deduped = new Set();
+        if (req.primaryFile)
+            deduped.add(req.primaryFile);
+        for (const file of result.meta.includedFiles ?? []) {
+            if (file)
+                deduped.add(file);
+        }
+        for (const target of result.context.targets ?? []) {
+            if (target.path)
+                deduped.add(target.path);
+        }
+        return [...deduped].sort().slice(0, ContextService.MAX_CACHE_TRACKED_FILES);
+    }
+    async computeTrackedFilesSignature(repoPath, files) {
+        const parts = [];
+        for (const relativeFile of files) {
+            const absoluteFile = defaultPathAdapter.resolve(repoPath, relativeFile);
+            try {
+                const stat = await this.fileAdapter.stat(absoluteFile);
+                parts.push(`${relativeFile}:${stat.mtimeMs}:${stat.size}`);
+            }
+            catch {
+                parts.push(`${relativeFile}:missing`);
+            }
+        }
+        if (files.length === 0) {
+            parts.push('files:none');
+        }
+        parts.push(...(await this.computeRepoStateSignatureParts(repoPath)));
+        return createHash('sha1').update(parts.join('|')).digest('hex');
+    }
+    async computeRepoStateSignatureParts(repoPath) {
+        const gitFiles = ['.git/HEAD', '.git/index'];
+        const parts = [];
+        for (const rel of gitFiles) {
+            const gitPath = defaultPathAdapter.resolve(repoPath, rel);
+            try {
+                const stat = await this.fileAdapter.stat(gitPath);
+                parts.push(`${rel}:${stat.mtimeMs}:${stat.size}`);
+            }
+            catch {
+                parts.push(`${rel}:missing`);
+            }
+        }
+        return parts;
+    }
+    getEntryTimestamp(entry) {
+        return entry.lastAccessedAt ?? entry.createdAt ?? 0;
+    }
+    async bumpCacheEntry(cacheKey) {
+        const entry = await this.cacheStore.get(cacheKey);
+        if (!entry)
+            return;
+        const now = Date.now();
+        entry.createdAt = entry.createdAt ?? now;
+        entry.lastAccessedAt = now;
+        await this.cacheStore.set(cacheKey, entry);
+    }
+    async isExpired(cacheKey, entry) {
+        const last = this.getEntryTimestamp(entry);
+        if (!last || Date.now() - last <= this.cacheTtlMs)
+            return false;
+        await this.cacheStore.delete(cacheKey);
+        this.cacheMetrics.evictions += 1;
+        return true;
+    }
+    async evictExpiredEntries() {
+        for (const [key, entry] of await this.cacheStore.entries()) {
+            await this.isExpired(key, entry);
+        }
+    }
+    async evictLruIfNeeded() {
+        while ((await this.cacheStore.size()) > this.cacheMaxEntries) {
+            let victimKey;
+            let victimTs = Number.POSITIVE_INFINITY;
+            for (const [key, entry] of await this.cacheStore.entries()) {
+                const ts = this.getEntryTimestamp(entry);
+                if (ts < victimTs) {
+                    victimTs = ts;
+                    victimKey = key;
+                }
+            }
+            if (!victimKey)
+                break;
+            await this.cacheStore.delete(victimKey);
+            this.cacheMetrics.evictions += 1;
+        }
+    }
+    async getCacheStats() {
+        const total = this.cacheMetrics.hits + this.cacheMetrics.misses;
+        const hitRate = total > 0 ? this.cacheMetrics.hits / total : 0;
+        return {
+            size: await this.cacheStore.size(),
+            maxEntries: this.cacheMaxEntries,
+            ttlMs: this.cacheTtlMs,
+            hits: this.cacheMetrics.hits,
+            misses: this.cacheMetrics.misses,
+            evictions: this.cacheMetrics.evictions,
+            hitRate,
+        };
+    }
+    recordContextDiff(key, contextResult) {
+        const updater = this.getUpdater(key);
+        const diff = updater.computeDiff(contextResult.context);
+        this.logDiff(key, diff);
+        this.logPromptCacheStats(key);
+    }
+    getUpdater(key) {
+        let updater = this.updaters.get(key);
+        if (!updater) {
+            updater = new IncrementalUpdater();
+            this.updaters.set(key, updater);
+        }
+        return updater;
+    }
+    logDiff(key, diff) {
+        if (!diff.addedFiles.length && !diff.modifiedFiles.length && !diff.removedFiles.length) {
+            return;
+        }
+        getLogger().trace(`[CONTEXT_CACHE] ${key} diff added=${diff.addedFiles.length} modified=${diff.modifiedFiles.length} removed=${diff.removedFiles.length}`);
+    }
+    logPromptCacheStats(key) {
+        const stats = this.promptCachingManager.getStats();
+        getLogger().trace(`[PROMPT_CACHE] ${key} provider=${stats.provider} hitRate=${(stats.cacheHitRate * 100).toFixed(1)}% cachedTokens=${stats.cachedTokens}`);
+    }
+}
+//# sourceMappingURL=service.js.map

package/dist/core/context/steps/context-budget.js

@@ -0,0 +1,157 @@
+import { LIMITS } from '../../config/limits.js';
+import { DefaultPromptAssembler } from '../assembly/default-prompt-assembler.js';
+import { CONTEXT_AUDIT_ACTION, CONTEXT_AUDIT_PHASE } from '../audit-constants.js';
+import { recordContextAuditEvent } from '../audit.js';
+import { applySmartCompression } from '../compression/smart-compress.js';
+import { createContextHash, createIntentSignature } from '../hash.js';
+import { buildContextBudgetPolicyPlan, executeContextBudgetPolicyPlan, } from '../policies/budget-policy.js';
+import { packUntilFull } from '../policies/pack-until-full.js';
+import { rankContextForRelevance } from '../scoring/relevance.js';
+import { calculateSectionChars, calculateUsedChars } from '../service-helpers.js';
+const BUDGET_RATIO = {
+    primary: 0.6,
+    related: 0.3,
+    secondary: 0.1,
+};
+function computeBudgetAllocation(budgetChars, sectionChars) {
+    const primaryBudget = Math.max(0, Math.floor(budgetChars * BUDGET_RATIO.primary));
+    const relatedBudget = Math.max(0, Math.floor(budgetChars * BUDGET_RATIO.related));
+    const secondaryBudget = Math.max(0, budgetChars - primaryBudget - relatedBudget);
+    const secondaryUsed = Math.max(0, sectionChars.rgSnippets + sectionChars.diffs);
+    return {
+        ratio: {
+            primary: BUDGET_RATIO.primary,
+            related: BUDGET_RATIO.related,
+            secondary: BUDGET_RATIO.secondary,
+        },
+        budgetChars: {
+            primary: primaryBudget,
+            related: relatedBudget,
+            secondary: secondaryBudget,
+        },
+        usedChars: {
+            primary: sectionChars.primary,
+            related: sectionChars.relatedFiles,
+            secondary: secondaryUsed,
+        },
+    };
+}
+export function buildContextBudgetStep(deps) {
+    const assembler = deps.assembler ?? new DefaultPromptAssembler();
+    return async ({ req, diffScope, primaryText, rgSnippets, targets, targetSetSignature, includedFiles, stagedDiff, unstagedDiff, gitDiff, relatedFiles, symbols, definitionMap, analysis, repoMap, symbolMap, projectMetadata, gitHistory, projectTopology, knowledgeBase, runtimeArtifacts, }) => {
+        const workspaceMode = req.workspaceMode ?? 'direct';
+        const context = {
+            repoPath: req.repoPath,
+            instruction: req.instruction,
+            primaryFile: req.primaryFile,
+            workspaceMode,
+            primaryText,
+            relatedFiles,
+            rgSnippets,
+            gitDiff,
+            stagedDiff,
+            unstagedDiff,
+            untrackedDiff: undefined,
+            untrackedFiles: [],
+            symbols,
+            definitionMap,
+            targets,
+            analysis,
+            repoMap,
+            symbolMap,
+            projectMetadata,
+            gitHistory,
+            projectTopology,
+            knowledgeBase,
+            runtimeArtifacts,
+        };
+        const compressed = applySmartCompression(context, { budgetChars: req.budgetChars });
+        const ranked = rankContextForRelevance(compressed);
+        const preBudgetSectionChars = calculateSectionChars(ranked);
+        const budgetPolicyPlan = buildContextBudgetPolicyPlan({
+            requestedBudgetChars: req.budgetChars,
+            preBudgetSectionChars,
+            targetCount: (ranked.targets ?? []).length,
+        });
+        recordContextAuditEvent(CONTEXT_AUDIT_ACTION.budgetPolicyPlan, {
+            workerId: budgetPolicyPlan.workerId,
+            actions: budgetPolicyPlan.actions.map((a) => a.type),
+            decisionTree: budgetPolicyPlan.decisionTree,
+        }, { source: 'context', severity: 'low', scope: 'session', phase: CONTEXT_AUDIT_PHASE.budget });
+        recordContextAuditEvent(CONTEXT_AUDIT_ACTION.relevanceRanking, {
+            topRelatedFiles: (ranked.relatedFiles ?? []).slice(0, 10).map((f) => ({
+                path: f.path,
+                kind: f.kind,
+                mode: f.mode,
+            })),
+            snippetFiles: Array.from(new Set((ranked.rgSnippets ?? []).slice(0, 20).map((s) => s.file))),
+        }, { source: 'context', severity: 'low', scope: 'session', phase: CONTEXT_AUDIT_PHASE.budget });
+        const budget = req.budgetChars;
+        const budgeted = executeContextBudgetPolicyPlan({
+            plan: budgetPolicyPlan,
+            context: ranked,
+            fallbackBudgetChars: budget ?? LIMITS.maxContextChars,
+            pack: packUntilFull,
+        });
+        const assembled = assembler.assemble(budgeted.context, req);
+        const contextHash = createContextHash(budgeted.context);
+        const sectionChars = calculateSectionChars(budgeted.context);
+        const requestedBudgetChars = budget ?? LIMITS.maxContextChars;
+        const budgetAllocation = computeBudgetAllocation(requestedBudgetChars, sectionChars);
+        const droppedSections = budgeted.truncated && preBudgetSectionChars.diffs > 0
+            ? {
+                stagedDiff: ranked.stagedDiff !== undefined && budgeted.context.stagedDiff === undefined,
+                unstagedDiff: ranked.unstagedDiff !== undefined && budgeted.context.unstagedDiff === undefined,
+                gitDiff: ranked.gitDiff !== undefined && budgeted.context.gitDiff === undefined,
+                untrackedDiff: ranked.untrackedDiff !== undefined && budgeted.context.untrackedDiff === undefined,
+            }
+            : undefined;
+        recordContextAuditEvent(CONTEXT_AUDIT_ACTION.packSummary, {
+            intentSignature: createIntentSignature({
+                instruction: req.instruction,
+                primaryFile: req.primaryFile,
+                selection: req.selection,
+                diffScope: req.diffScope,
+            }),
+            targetSetSignature,
+            cacheKeyHint: [
+                req.repoPath,
+                req.snapshotHash ?? '',
+                req.diffScope ?? 'primary',
+                workspaceMode,
+            ].join('::'),
+            requestedBudgetChars: budget,
+            preBudgetSectionChars,
+            sectionChars,
+            budgetAllocation,
+            truncated: budgeted.truncated,
+            droppedSections,
+        }, { source: 'context', severity: 'low', scope: 'session', phase: CONTEXT_AUDIT_PHASE.budget });
+        return {
+            context: {
+                ...budgeted.context,
+                contextHash,
+                targetSetSignature,
+            },
+            prompt: assembled.prompt,
+            meta: {
+                usedChars: calculateUsedChars(budgeted.context),
+                truncated: budgeted.truncated,
+                diffScope,
+                includedFiles,
+                requestedBudgetChars: budget,
+                preBudgetSectionChars,
+                sectionChars,
+                budgetAllocation,
+                contextHash,
+                targetSetSignature,
+                environment: {
+                    workspaceMode,
+                },
+                droppedSections,
+                ...(assembled.meta || {}),
+            },
+        };
+    };
+}
+//# sourceMappingURL=context-budget.js.map

package/dist/core/context/steps/context-gather.js

@@ -0,0 +1,71 @@
+import { CONTEXT_AUDIT_ACTION, CONTEXT_AUDIT_PHASE } from '../audit-constants.js';
+import { recordContextAuditEvent } from '../audit.js';
+import { extractKeywords } from '../keywords.js';
+import { assertNotAborted } from '../service-helpers.js';
+export function buildContextGatherStep(deps) {
+    return async ({ req, diffScope, primaryText }) => {
+        assertNotAborted(req.signal);
+        const keywords = extractKeywords(req.instruction);
+        recordContextAuditEvent(CONTEXT_AUDIT_ACTION.keywordsExtracted, { count: keywords.length, keywords: keywords.slice(0, 5) }, { source: 'context', severity: 'low', scope: 'session', phase: CONTEXT_AUDIT_PHASE.gather });
+        const [rgSnippets, diffRes, astRes, projectMetadata, gitHistory, projectTopology, knowledgeBase, runtimeArtifacts,] = await Promise.all([
+            deps.ripgrepGatherer.searchMultipleKeywords(keywords, req.repoPath, req.signal),
+            deps.gitDiffGatherer.gather({ ...req, diffScope }),
+            deps.astGatherer.gather(primaryText, req),
+            deps.metadataGatherer.gather(req),
+            deps.gitHistoryGatherer.gather(req),
+            deps.architectureGatherer.gather(req),
+            deps.knowledgeGatherer.gather(req),
+            deps.artifactGatherer.gather(req),
+        ]);
+        assertNotAborted(req.signal);
+        // 2nd Stage: Semantic/Ghost Dependency Probe
+        const existingFiles = new Set(astRes.relatedFiles.map((f) => f.path));
+        const ghostFiles = await deps.ghostDependencyGatherer.gather(primaryText, req, existingFiles);
+        if (ghostFiles.length > 0) {
+            astRes.relatedFiles.push(...ghostFiles);
+        }
+        recordContextAuditEvent(CONTEXT_AUDIT_ACTION.gatherCompleted, {
+            rgSnippets: rgSnippets.length,
+            includedFiles: diffRes.includedFiles.length,
+            importedFiles: astRes.relatedFiles.length,
+            ghostFiles: ghostFiles.length,
+            syntaxErrors: astRes.syntaxErrors?.length ?? 0,
+            hasParseError: Boolean(astRes.parseError),
+            hasProjectMetadata: Boolean(projectMetadata),
+            hasGitHistory: Boolean(gitHistory),
+            hasProjectTopology: Boolean(projectTopology),
+            hasKnowledgeBase: Boolean(knowledgeBase),
+            hasRuntimeArtifacts: Boolean(runtimeArtifacts),
+        }, { source: 'context', severity: 'low', scope: 'session', phase: CONTEXT_AUDIT_PHASE.gather });
+        return {
+            req,
+            diffScope,
+            primaryText,
+            rgSnippets,
+            projectMetadata,
+            gitHistory,
+            projectTopology,
+            knowledgeBase,
+            runtimeArtifacts,
+            diff: {
+                includedFiles: diffRes.includedFiles,
+                stagedDiff: diffRes.stagedDiff,
+                unstagedDiff: diffRes.unstagedDiff,
+                gitDiff: diffRes.gitDiff,
+            },
+            ast: {
+                relatedFiles: astRes.relatedFiles,
+                repoMap: astRes.repoMap,
+                symbolMap: astRes.symbolMap,
+                controlFlow: astRes.controlFlow,
+                exceptionPaths: astRes.exceptionPaths,
+                symbols: astRes.symbols,
+                definitionMap: astRes.definitionMap,
+                languageId: astRes.languageId,
+                syntaxErrors: astRes.syntaxErrors,
+                parseError: astRes.parseError,
+            },
+        };
+    };
+}
+//# sourceMappingURL=context-gather.js.map

package/dist/core/context/steps/context-primary.js

@@ -0,0 +1,19 @@
+import { CONTEXT_AUDIT_ACTION, CONTEXT_AUDIT_PHASE } from '../audit-constants.js';
+import { recordContextAuditEvent } from '../audit.js';
+import { assertNotAborted } from '../service-helpers.js';
+export function buildContextPrimaryStep(deps) {
+    return async ({ req, diffScope }) => {
+        assertNotAborted(req.signal);
+        recordContextAuditEvent(CONTEXT_AUDIT_ACTION.inputSummary, {
+            hasPrimaryFile: Boolean(req.primaryFile),
+            hasSelection: Boolean(req.selection),
+            instructionChars: req.instruction?.length ?? 0,
+            diffScope,
+            budgetChars: req.budgetChars ?? null,
+        }, { source: 'context', severity: 'low', scope: 'session', phase: CONTEXT_AUDIT_PHASE.primary });
+        const { primaryText } = await deps.primaryTextGatherer.gather(req);
+        assertNotAborted(req.signal);
+        return { req, diffScope, primaryText };
+    };
+}
+//# sourceMappingURL=context-primary.js.map

package/dist/core/context/steps/context-promotion.js

@@ -0,0 +1,78 @@
+import { FileAdapter } from '../../adapters/fs/file-adapter.js';
+import { LIMITS } from '../../config/limits.js';
+import { ensureInSandbox, normalizePath, safeJoin } from '../../utils/path.js';
+import { CONTEXT_AUDIT_ACTION, CONTEXT_AUDIT_PHASE } from '../audit-constants.js';
+import { recordContextAuditEvent } from '../audit.js';
+import { rankContextForRelevance } from '../scoring/relevance.js';
+import { assertNotAborted } from '../service-helpers.js';
+const fileAdapter = new FileAdapter();
+/**
+ * Promotes high-relevance 'outline' files to 'full' content.
+ * This effectively breaks the 'static snapshot' limitation by performing
+ * a second-stage targeted read based on initial ranking.
+ */
+export function buildContextPromotionStep(_deps) {
+    return async (ctx) => {
+        const { req } = ctx;
+        assertNotAborted(req.signal);
+        // 1. Create temporary context for ranking
+        const tempContext = {
+            repoPath: req.repoPath,
+            instruction: req.instruction,
+            primaryFile: req.primaryFile,
+            primaryText: ctx.primaryText,
+            relatedFiles: ctx.relatedFiles,
+            rgSnippets: ctx.rgSnippets,
+            targets: ctx.targets,
+            symbolMap: ctx.symbolMap,
+            repoMap: ctx.repoMap,
+        };
+        // 2. Rank to find high-relevance candidates
+        const ranked = rankContextForRelevance(tempContext);
+        const candidates = (ranked.relatedFiles ?? []).filter((f) => f.mode === 'outline').slice(0, 5); // Promote up to Top 5 high-relevance outlines
+        if (candidates.length === 0)
+            return ctx;
+        const promotedPaths = [];
+        const updatedRelatedFiles = [...(ctx.relatedFiles ?? [])];
+        for (const candidate of candidates) {
+            // Check if score is high enough to justify promotion
+            // In a real system, we'd check the score, but here we'll use a heuristic:
+            // if it's in the top 5 and matched keywords or targets.
+            try {
+                const normalized = normalizePath(candidate.path).replace(/^(\.\/|\/)+/, '');
+                const fullPath = ensureInSandbox(req.repoPath, safeJoin(req.repoPath, normalized));
+                const content = await fileAdapter.readFile(fullPath, 'utf-8');
+                // Only promote if not obscenely large
+                if (content.length < LIMITS.largeFileThresholdBytes * 2) {
+                    const index = updatedRelatedFiles.findIndex((f) => f.path === candidate.path);
+                    if (index !== -1) {
+                        updatedRelatedFiles[index] = {
+                            ...updatedRelatedFiles[index],
+                            mode: 'full',
+                            content: content,
+                            outline: updatedRelatedFiles[index].outline || candidate.content, // preserve original outline if needed
+                        };
+                        promotedPaths.push(candidate.path);
+                    }
+                }
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error ?? 'Unknown error');
+                recordContextAuditEvent(CONTEXT_AUDIT_ACTION.promotionFailed, { path: candidate.path, error: message }, {
+                    source: 'context',
+                    severity: 'medium',
+                    scope: 'session',
+                    phase: CONTEXT_AUDIT_PHASE.promotion,
+                });
+            }
+        }
+        if (promotedPaths.length > 0) {
+            recordContextAuditEvent(CONTEXT_AUDIT_ACTION.promotionCompleted, { count: promotedPaths.length, paths: promotedPaths }, { source: 'context', severity: 'low', scope: 'session', phase: CONTEXT_AUDIT_PHASE.gather });
+        }
+        return {
+            ...ctx,
+            relatedFiles: updatedRelatedFiles,
+        };
+    };
+}
+//# sourceMappingURL=context-promotion.js.map

package/dist/core/context/steps/context-targets.js

@@ -0,0 +1,85 @@
+import { CONTEXT_AUDIT_ACTION, CONTEXT_AUDIT_PHASE } from '../audit-constants.js';
+import { recordContextAuditEvent } from '../audit.js';
+import { createIntentSignature } from '../hash.js';
+import { assertNotAborted } from '../service-helpers.js';
+export function buildContextTargetsStep(deps) {
+    return async ({ req, diffScope, primaryText, rgSnippets, projectMetadata, gitHistory, projectTopology, knowledgeBase, runtimeArtifacts, diff, ast, }) => {
+        assertNotAborted(req.signal);
+        const importRelatedFiles = (ast.relatedFiles ?? []).map((f) => f.path);
+        const rgHitFiles = Array.from(new Set((rgSnippets ?? []).map((s) => s.file)));
+        const symbolCandidates = req.instruction.match(/\b[A-Za-z_][A-Za-z0-9_]{2,}\b/g) ?? [];
+        recordContextAuditEvent(CONTEXT_AUDIT_ACTION.targetingCandidates, {
+            explicitPathCandidates: (req.instruction.match(/\.\w{1,5}\b/g) || []).length,
+            symbolCandidates: symbolCandidates.slice(0, 20),
+        }, { source: 'context', severity: 'low', scope: 'session', phase: CONTEXT_AUDIT_PHASE.targets });
+        const { targets, diffusionMetrics, targetSetSignature } = await deps.targetResolver.resolve({
+            req,
+            includedFiles: diff.includedFiles,
+            importRelatedFiles,
+            rgHitFiles,
+            definitionMap: ast.definitionMap,
+            symbolMap: ast.symbolMap,
+            churnByFile: gitHistory?.churnByFile,
+        });
+        assertNotAborted(req.signal);
+        recordContextAuditEvent(CONTEXT_AUDIT_ACTION.targetsResolved, {
+            intentSignature: createIntentSignature({
+                instruction: req.instruction,
+                primaryFile: req.primaryFile,
+                selection: req.selection,
+                diffScope: req.diffScope,
+            }),
+            targetSetSignature,
+            strategyTargets: targets.map((t) => ({
+                path: t.path,
+                reason: t.reason,
+                confidence: t.confidence,
+                churnWeight: t.churnWeight,
+                ranking: t.ranking,
+            })),
+            diffusionMetrics: diffusionMetrics
+                ? {
+                    totalCandidates: diffusionMetrics.totalCandidates,
+                    selectedTargets: diffusionMetrics.selectedTargets,
+                    budgetLimit: diffusionMetrics.budgetLimit,
+                    sourceBreakdown: diffusionMetrics.sourceBreakdown,
+                }
+                : undefined,
+        }, { source: 'context', severity: 'low', scope: 'session', phase: CONTEXT_AUDIT_PHASE.targets });
+        return {
+            req,
+            diffScope,
+            primaryText,
+            rgSnippets,
+            targets,
+            targetSetSignature,
+            projectMetadata,
+            gitHistory,
+            projectTopology,
+            knowledgeBase,
+            runtimeArtifacts,
+            includedFiles: diff.includedFiles,
+            stagedDiff: diff.stagedDiff,
+            unstagedDiff: diff.unstagedDiff,
+            gitDiff: diff.gitDiff,
+            relatedFiles: ast.relatedFiles,
+            symbols: ast.symbols,
+            definitionMap: ast.definitionMap,
+            repoMap: ast.repoMap,
+            symbolMap: ast.symbolMap,
+            analysis: {
+                ast: {
+                    languageId: ast.languageId,
+                    syntaxErrors: ast.syntaxErrors,
+                    parseError: ast.parseError,
+                    controlFlow: ast.controlFlow,
+                    exceptionPaths: ast.exceptionPaths,
+                    notes: [
+                        'Type mismatch, dead code, and potential bug detection are not available in this analysis layer.',
+                    ],
+                },
+            },
+        };
+    };
+}
+//# sourceMappingURL=context-targets.js.map

package/dist/core/context/steps/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map