@devflow-tools/context-engine 0.16.34 → 0.17.1

package/dist/channel-query-planner.d.ts

@@ -0,0 +1,9 @@
+import type { ChannelQueryPlan, ImmutableTaskIntentArtifact } from '@devflow-tools/sdk';
+import type { RetrievalTaskPlan } from './retrieval-task-plan.js';
+export declare function buildChannelQueryPlan(input: {
+    artifact: ImmutableTaskIntentArtifact;
+    taskPlan: RetrievalTaskPlan;
+    expandedTerms?: string;
+    generatedBy?: ChannelQueryPlan['generatedBy'];
+}): ChannelQueryPlan;
+//# sourceMappingURL=channel-query-planner.d.ts.map

package/dist/channel-query-planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-query-planner.d.ts","sourceRoot":"","sources":["../src/channel-query-planner.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,gBAAgB,EAEhB,2BAA2B,EAG5B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,wBAAgB,qBAAqB,CAAC,KAAK,EAAE;IAC3C,QAAQ,EAAE,2BAA2B,CAAC;IACtC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,gBAAgB,CAAC,aAAa,CAAC,CAAC;CAC/C,GAAG,gBAAgB,CA6CnB"}

package/dist/channel-query-planner.js

@@ -0,0 +1,92 @@
+import { createHash } from 'node:crypto';
+export function buildChannelQueryPlan(input) {
+    const authoritativeQuery = taskQuery(input.artifact);
+    const expanded = boundedQuery(input.expandedTerms);
+    const retrievalQuery = expanded ? `${authoritativeQuery} ${expanded}` : authoritativeQuery;
+    const code = input.artifact.intent === 'memory'
+        ? []
+        : [{
+                query: retrievalQuery,
+                targetAnchors: [...input.artifact.targetAnchors],
+                symbols: [...input.taskPlan.symbols],
+                relationKinds: relationKinds(input.taskPlan),
+                maxDepth: input.artifact.targetAnchors.length > 0 ? 1 : 2,
+            }];
+    const memory = [{
+            query: authoritativeQuery,
+            scopes: input.artifact.activeSkill ? ['project', 'skill', 'session'] : ['project', 'session'],
+            entities: [...input.taskPlan.entities],
+            facets: [...input.taskPlan.requiredPolicyFacets],
+            requireVerifiedEvidence: true,
+        }];
+    const knowledge = input.taskPlan.knowledgeNeeds.length > 0
+        ? input.taskPlan.knowledgeNeeds.map(need => ({
+            query: queryForKnowledgeNeed(need, authoritativeQuery),
+            requirement: need.required ? 'knowledge_required' : 'knowledge_optional',
+            kind: need.kind,
+            ...(need.entity ? { entity: need.entity } : {}),
+            ...(need.symbol ? { symbol: need.symbol } : {}),
+            ...(need.version ? { version: need.version } : {}),
+        }))
+        : [{
+                query: '',
+                requirement: 'knowledge_not_required',
+                kind: 'overview',
+            }];
+    const createdAt = input.artifact.createdAt;
+    const planBody = {
+        identity: input.artifact.identity,
+        sourceIntentHash: input.artifact.artifactHash,
+        code,
+        memory,
+        knowledge,
+        generatedBy: input.generatedBy ?? (expanded ? 'hybrid' : 'deterministic'),
+        createdAt,
+    };
+    return { ...planBody, planHash: stableHash(planBody) };
+}
+function taskQuery(artifact) {
+    const withoutCommand = artifact.command
+        ? artifact.normalizedPrompt.replace(new RegExp(`^\\/${escapeRegExp(artifact.command)}\\b`, 'iu'), '').trim()
+        : artifact.normalizedPrompt;
+    return boundedQuery(withoutCommand) || boundedQuery(artifact.rawPrompt) || artifact.action;
+}
+function boundedQuery(value) {
+    return value?.normalize('NFKC').replace(/\s+/gu, ' ').trim().slice(0, 2_000) ?? '';
+}
+function relationKinds(plan) {
+    const kinds = new Set(['dependency']);
+    if (['debug', 'modify', 'analyze'].includes(plan.action))
+        kinds.add('caller');
+    if (plan.intent === 'performance')
+        kinds.add('caller');
+    if (plan.action === 'create') {
+        kinds.add('route');
+        kinds.add('config');
+    }
+    if (plan.action === 'test')
+        kinds.add('test');
+    return [...kinds];
+}
+function queryForKnowledgeNeed(need, fallback) {
+    return [need.entity, need.symbol, need.kind, need.version].filter(Boolean).join(' ') || fallback;
+}
+function stableHash(value) {
+    return createHash('sha256').update(stableJson(value)).digest('hex');
+}
+function stableJson(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return JSON.stringify(value);
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? JSON.stringify(value) : 'null';
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(',')}]`;
+    if (!value || typeof value !== 'object')
+        return JSON.stringify(String(value));
+    const record = value;
+    return `{${Object.keys(record).sort().map(key => `${JSON.stringify(key)}:${stableJson(record[key])}`).join(',')}}`;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+//# sourceMappingURL=channel-query-planner.js.map

package/dist/channel-query-planner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-query-planner.js","sourceRoot":"","sources":["../src/channel-query-planner.ts"],"names":[],"mappings":"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"}

package/dist/context-budget-allocator.d.ts

@@ -0,0 +1,19 @@
+export interface BudgetedContextCandidate {
+    path: string;
+    score: number;
+    source: 'structural' | 'graph';
+}
+export interface ContextBudgetAllocation {
+    selectedPaths: Set<string>;
+    rejectedPaths: Set<string>;
+    maxFiles: number;
+    graphFileLimit: number;
+    selectedGraphFiles: number;
+}
+export declare function allocateContextFileBudget(input: {
+    requiredPaths: Iterable<string>;
+    candidates: BudgetedContextCandidate[];
+    tokenBudget: number;
+    graphRatio?: number;
+}): ContextBudgetAllocation;
+//# sourceMappingURL=context-budget-allocator.d.ts.map

package/dist/context-budget-allocator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget-allocator.d.ts","sourceRoot":"","sources":["../src/context-budget-allocator.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,uBAAuB;IACtC,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChC,UAAU,EAAE,wBAAwB,EAAE,CAAC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,uBAAuB,CAqB1B"}

package/dist/context-budget-allocator.js

@@ -0,0 +1,35 @@
+export function allocateContextFileBudget(input) {
+    const required = new Set(input.requiredPaths);
+    const maxFiles = Math.max(required.size, Math.max(5, Math.min(24, Math.floor(input.tokenBudget / 280))));
+    const remaining = Math.max(0, maxFiles - required.size);
+    const graphFileLimit = Math.min(remaining, Math.max(1, Math.floor(maxFiles * (input.graphRatio ?? 0.2))));
+    const structural = dedupe(input.candidates.filter(candidate => candidate.source === 'structural'));
+    const graph = dedupe(input.candidates.filter(candidate => candidate.source === 'graph'));
+    const selectedPaths = new Set(required);
+    for (const candidate of structural) {
+        if (selectedPaths.size >= maxFiles)
+            break;
+        selectedPaths.add(candidate.path);
+    }
+    let selectedGraphFiles = 0;
+    for (const candidate of graph) {
+        if (selectedPaths.size >= maxFiles || selectedGraphFiles >= graphFileLimit)
+            break;
+        if (selectedPaths.has(candidate.path))
+            continue;
+        selectedPaths.add(candidate.path);
+        selectedGraphFiles += 1;
+    }
+    const rejectedPaths = new Set(input.candidates.map(candidate => candidate.path).filter(path => !selectedPaths.has(path)));
+    return { selectedPaths, rejectedPaths, maxFiles, graphFileLimit, selectedGraphFiles };
+}
+function dedupe(candidates) {
+    const byPath = new Map();
+    for (const candidate of candidates) {
+        const existing = byPath.get(candidate.path);
+        if (!existing || candidate.score > existing.score)
+            byPath.set(candidate.path, candidate);
+    }
+    return [...byPath.values()].sort((left, right) => right.score - left.score || left.path.localeCompare(right.path));
+}
+//# sourceMappingURL=context-budget-allocator.js.map

package/dist/context-budget-allocator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget-allocator.js","sourceRoot":"","sources":["../src/context-budget-allocator.ts"],"names":[],"mappings":"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"}

package/dist/context-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-engine.d.ts","sourceRoot":"","sources":["../src/context-engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EAEb,WAAW,EACX,aAAa,EAOb,sBAAsB,EACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAA0B,MAAM,iCAAiC,CAAC;AAC/F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAwB,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAQzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAU3D,OAAO,KAAK,EAKV,kBAAkB,EAClB,+BAA+B,EAChC,MAAM,YAAY,CAAC;AAuSpB,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,SAAS,CAAC;IACd,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,cAAc,CAAC;IACxB,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,EAAE,eAAe,CAAC;IAC3B,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAoCD,qBAAa,aAAa;IACxB,OAAO,CAAC,EAAE,CAAY;IACtB,OAAO,CAAC,IAAI,CAAgB;IAC5B,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,QAAQ,CAAC,CAAoB;IACrC,OAAO,CAAC,WAAW,CAAC,CAAoB;IACxC,OAAO,CAAC,cAAc,CAAC,CAAiB;gBAE5B,IAAI,EAAE,iBAAiB;IAYnC,KAAK,IAAI,IAAI;IAKb,OAAO,CAAC,UAAU,CAAkD;IAE9D,gCAAgC,CAAC,KAAK,EAAE;QAC5C,OAAO,EAAE,sBAAsB,EAAE,CAAC;QAClC,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC;QACd,cAAc,EAAE,MAAM,CAAC;KACxB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIX,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhD,OAAO,CAAC,yBAAyB;YA4BnB,yBAAyB;IAiCvC,OAAO,CAAC,eAAe;IAKjB,KAAK,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAmRtD,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,+BAA+B,CAAC;YA4iB/F,sBAAsB;IAmWpC,OAAO,CAAC,yBAAyB;YAgBnB,2BAA2B;YA4B3B,6BAA6B;IAkB3C,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,sBAAsB;IAM9B,OAAO,CAAC,2BAA2B;IAOnC,SAAS,IAAI,WAAW;CASzB"}
+{"version":3,"file":"context-engine.d.ts","sourceRoot":"","sources":["../src/context-engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EAEb,WAAW,EACX,aAAa,EAOb,sBAAsB,EACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAA0B,MAAM,iCAAiC,CAAC;AAC/F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAwB,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAQzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAU3D,OAAO,KAAK,EAKV,kBAAkB,EAClB,+BAA+B,EAChC,MAAM,YAAY,CAAC;AA0SpB,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,SAAS,CAAC;IACd,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,cAAc,CAAC;IACxB,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,EAAE,eAAe,CAAC;IAC3B,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAoCD,qBAAa,aAAa;IACxB,OAAO,CAAC,EAAE,CAAY;IACtB,OAAO,CAAC,IAAI,CAAgB;IAC5B,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,QAAQ,CAAC,CAAoB;IACrC,OAAO,CAAC,WAAW,CAAC,CAAoB;IACxC,OAAO,CAAC,cAAc,CAAC,CAAiB;gBAE5B,IAAI,EAAE,iBAAiB;IAYnC,KAAK,IAAI,IAAI;IAKb,OAAO,CAAC,UAAU,CAAkD;IAE9D,gCAAgC,CAAC,KAAK,EAAE;QAC5C,OAAO,EAAE,sBAAsB,EAAE,CAAC;QAClC,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC;QACd,cAAc,EAAE,MAAM,CAAC;KACxB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIX,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhD,OAAO,CAAC,yBAAyB;YAoCnB,yBAAyB;IAiCvC,OAAO,CAAC,eAAe;IAKjB,KAAK,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAkRtD,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,+BAA+B,CAAC;YA8nB/F,sBAAsB;IAsWpC,OAAO,CAAC,yBAAyB;YAgBnB,2BAA2B;YA4B3B,6BAA6B;IAkB3C,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,sBAAsB;IAM9B,OAAO,CAAC,2BAA2B;IAOnC,SAAS,IAAI,WAAW;CASzB"}

package/dist/context-engine.js

@@ -11,6 +11,9 @@ import { reachableCodeGraphNodeIds, sanitizeCodeGraphEdges, } from './graph-edge
 import { assembleContextFileRoles } from './context-file-roles.js';
 import { buildTaskContextEnvelope } from './task-retrieval-orchestrator.js';
 import { recordTaskEnvelopeLedger } from './retrieval-ledger.js';
+import { selectGraphEvidence } from './graph-evidence-selector.js';
+import { allocateContextFileBudget } from './context-budget-allocator.js';
+import { emitSemanticControlLog } from '@devflow-tools/telemetry';
 const CG = CGModule.default ?? CGModule;
 const SYMBOL_VECTOR_WARNING = "Symbol vector search is not ready; using CodeGraph/BM25 results. Run `devflow doctor` for details.";
 // ── RRF (Reciprocal Rank Fusion) ─────────────────────────────────
@@ -317,6 +320,12 @@ export class ContextEngine {
             relevantFiles: options.relevantFiles,
             action: taskPlan?.action,
             knowledgeNeeds: taskPlan?.knowledgeNeeds,
+            sessionId: options.sessionId,
+            executionId: options.executionId,
+            requestId: options.requestId,
+            turnId: options.turnId,
+            intentArtifactHash: options.intentArtifact?.artifactHash,
+            queryPlanHash: options.queryPlan?.planHash,
             projectSignals: {
                 frameworks,
                 languages,
@@ -622,15 +631,27 @@ export class ContextEngine {
         }
         const intent = parseIntent(query);
         const taskType = intent.intent;
-        const combinedQuery = mergeQueries(query, expandQuery(query), options?.expandedTerms);
-        const targetAnchors = extractTargetAnchors(query);
+        const combinedQuery = options?.queryPlan?.code[0]?.query
+            ?? mergeQueries(query, expandQuery(query), options?.expandedTerms);
+        const targetAnchors = options?.intentArtifact?.targetAnchors ?? extractTargetAnchors(query);
         const retrievalTaskPlan = buildRetrievalTaskPlan({
             query,
             parsedIntent: intent,
             targetAnchors,
             activeSkill: options?.activeSkill,
             command: options?.command,
+            authoritativeArtifact: options?.intentArtifact,
         });
+        const projectRoot = this.cg.getProjectRoot?.() ?? process.cwd();
+        const logIdentity = {
+            projectRoot,
+            sessionId: options?.sessionId,
+            turnId: options?.turnId,
+            requestId: options?.requestId,
+            executionId: options?.executionId,
+            intentArtifactHash: options?.intentArtifact?.artifactHash,
+            queryPlanHash: options?.queryPlan?.planHash,
+        };
         const timing = {};
         const t0 = Date.now();
         const [cgResult, knowledgeResult, memoryHits] = await Promise.all([
@@ -645,7 +666,10 @@ export class ContextEngine {
                     }),
                     new Promise((_, reject) => setTimeout(() => reject(new Error("buildContext timeout")), 15000)),
                 ]).catch((err) => {
-                    console.error("[devflow] cg.buildContext failed, falling back:", err.message);
+                    emitSemanticControlLog({
+                        event: 'context.build.degraded', identity: logIdentity, level: 'warn', timestamp: Date.now(),
+                        data: { stage: 'codegraph_context', reason: err.message, fallback: 'manual_pipeline' },
+                    });
                     return null;
                 })
                 : Promise.resolve(null),
@@ -653,7 +677,10 @@ export class ContextEngine {
                 this.searchKnowledgeWithStatus(combinedQuery, this.getKnowledgeSearchOptions(combinedQuery, 5, options, retrievalTaskPlan, maxTokens)),
                 new Promise((_, reject) => setTimeout(() => reject(new Error("knowledge timeout")), 5000)),
             ]).catch((err) => {
-                console.error("[devflow] knowledge.search timeout:", err.message);
+                emitSemanticControlLog({
+                    event: 'knowledge.search.degraded', identity: logIdentity, level: 'warn', timestamp: Date.now(),
+                    data: { reason: err.message, fallback: 'knowledge_empty' },
+                });
                 return { entries: [], warnings: [`knowledge-search-failed: ${err.message}`] };
             }),
             typeof this.memory.search === "function"
@@ -668,18 +695,23 @@ export class ContextEngine {
                     }),
                     new Promise((_, reject) => setTimeout(() => reject(new Error("memory timeout")), 5000)),
                 ]).catch((err) => {
-                    console.error("[devflow] memory.search timeout:", err.message);
+                    emitSemanticControlLog({
+                        event: 'memory.search.completed', identity: logIdentity, level: 'warn', timestamp: Date.now(),
+                        data: { status: 'degraded', reason: err.message, selected: 0, fallback: 'memory_empty' },
+                    });
                     return [];
                 })
                 : Promise.resolve([]),
         ]);
         timing["1_promise_all"] = Date.now() - t0;
-        console.error("[devflow:timing] Promise.all:", timing["1_promise_all"], "ms");
         const knowledgeHits = knowledgeResult.entries;
         if (knowledgeResult.warnings.length > 0)
             warnings.push(...knowledgeResult.warnings);
         if (!cgResult) {
-            console.error("[devflow] buildContext failed, falling back to manual pipeline");
+            emitSemanticControlLog({
+                event: 'context.build.degraded', identity: logIdentity, level: 'warn', timestamp: Date.now(),
+                data: { stage: 'codegraph_context', reason: 'context_unavailable', fallback: 'manual_pipeline' },
+            });
             const result = await this.buildTaskContextLegacy(query, options);
             result._devflow = { fallback: "buildContext-unavailable" };
             return result;
@@ -691,7 +723,10 @@ export class ContextEngine {
                 ctx = JSON.parse(cgResult);
             }
             catch {
-                console.error("[devflow] buildContext returned unparseable string, falling back");
+                emitSemanticControlLog({
+                    event: 'context.build.degraded', identity: logIdentity, level: 'warn', timestamp: Date.now(),
+                    data: { stage: 'codegraph_parse', reason: 'unparseable_context', fallback: 'manual_pipeline' },
+                });
                 return this.buildTaskContextLegacy(query, options);
             }
         }
@@ -732,7 +767,6 @@ export class ContextEngine {
                 }
             }
         }
-        console.error("[devflow:timing] Fallback searchNodes loop:", Date.now() - tFallback, "ms");
         timing["2_fallback_loop"] = Date.now() - tFallback;
         const fileFreshnessByPath = new Map();
         if (this.indexer?.ensureFilesCurrent) {
@@ -770,7 +804,24 @@ export class ContextEngine {
         const anchoredEntryPoints = targetAnchors.length > 0
             ? originalEntryPoints.filter(entry => fileMatchesTargetAnchor(entry.filePath, targetAnchors))
             : originalEntryPoints;
-        const effectiveEntryPoints = anchoredEntryPoints.length > 0 ? anchoredEntryPoints : originalEntryPoints;
+        const graphSelection = selectGraphEvidence({
+            codegraph: this.cg,
+            candidates: originalEntryPoints,
+            symbols: retrievalTaskPlan.symbols,
+            targetAnchors,
+        });
+        const evidenceEntryPoints = graphSelection.selected.length > 0
+            ? graphSelection.selected
+            : originalEntryPoints;
+        const selectedAnchoredEntryPoints = targetAnchors.length > 0
+            ? evidenceEntryPoints.filter(entry => fileMatchesTargetAnchor(entry.filePath, targetAnchors))
+            : evidenceEntryPoints;
+        const effectiveEntryPoints = selectedAnchoredEntryPoints.length > 0
+            ? selectedAnchoredEntryPoints
+            : anchoredEntryPoints.length > 0 ? anchoredEntryPoints : evidenceEntryPoints;
+        if (graphSelection.ambiguities.length > 0) {
+            warnings.push(`codegraph-symbol-ambiguity:${graphSelection.ambiguities.length}`);
+        }
         const rootIds = new Set(effectiveEntryPoints.map((ep) => ep.id));
         const reachableNodeIds = reachableCodeGraphNodeIds(rootIds, edgeQuality.accepted);
         const entryFiles = new Set(effectiveEntryPoints.map((entry) => entry.filePath));
@@ -792,6 +843,7 @@ export class ContextEngine {
         const perFileCount = new Map();
         const MAX_SYMBOLS_PER_FILE = 5;
         const optionalCandidates = new Map();
+        const graphOptionalPaths = new Set();
         const queryTerms = combinedQuery.split(/\s+/).map(term => term.toLowerCase()).filter(term => term.length >= 3);
         for (const node of allNodes) {
             // Skip file wrappers and import edges — they're not actionable symbols
@@ -831,6 +883,7 @@ export class ContextEngine {
                             snippet: "",
                             distance,
                         });
+                        graphOptionalPaths.add(node.filePath);
                     }
                 }
             }
@@ -876,6 +929,21 @@ export class ContextEngine {
             }
         }
         let rankedOptionalFiles = rankOptionalContextFiles([...optionalCandidates.values()], taskType);
+        const codeBudget = allocateContextFileBudget({
+            requiredPaths: requiredFileSet,
+            candidates: rankedOptionalFiles.map(candidate => ({
+                path: candidate.path,
+                score: candidate.score,
+                source: fileRoleByPath.has(candidate.path) && fileRoleByPath.get(candidate.path)?.role !== 'dependency'
+                    ? 'structural'
+                    : graphOptionalPaths.has(candidate.path) ? 'graph' : 'structural',
+            })),
+            tokenBudget: Math.floor(maxTokens * 0.45),
+            graphRatio: 0.2,
+        });
+        rankedOptionalFiles = rankedOptionalFiles.filter(candidate => codeBudget.selectedPaths.has(candidate.path));
+        if (codeBudget.rejectedPaths.size > 0)
+            warnings.push(`codegraph-budget-rejected:${codeBudget.rejectedPaths.size}`);
         for (const candidate of rankedOptionalFiles)
             optionalFileSet.add(candidate.path);
         if (this.indexer?.getFileFreshness) {
@@ -943,7 +1011,6 @@ export class ContextEngine {
         const compressed = compressToTokenLimit(allFileSnippets, Math.floor(maxTokens * 0.45));
         if (compressed.overBudget)
             warnings.push("context-compressor-budget-exceeded");
-        console.error("[devflow:timing] Snippet building + compress:", Date.now() - tSnippet, "ms");
         timing["3_snippet_compress"] = Date.now() - tSnippet;
         const riskHints = generateRiskHints(allNodes.filter(node => node.kind !== "file" && node.kind !== "import"), graphEvidence);
         const nextActions = generateNextActions(taskType, keySymbols.slice(0, 5));
@@ -1072,9 +1139,18 @@ export class ContextEngine {
             requestId: options?.requestId,
             host: options?.host,
             command: options?.command,
+            turnId: options?.turnId,
+            intentArtifact: options?.intentArtifact,
+            queryPlan: options?.queryPlan,
             tokenBudget: maxTokens,
             targetAnchors,
             taskPlan: retrievalTaskPlan,
+            graphAmbiguities: graphSelection.ambiguities,
+            codeBudget: {
+                maxFiles: codeBudget.maxFiles,
+                graphFileLimit: codeBudget.graphFileLimit,
+                selectedGraphFiles: codeBudget.selectedGraphFiles,
+            },
             fileRoles: fileRoleByPath,
             fileFreshness: fileFreshnessByPath,
             memoryHits,
@@ -1110,7 +1186,23 @@ export class ContextEngine {
             this.queryCache.set(cacheKey, result);
         }
         timing["0_total"] = Date.now() - t0;
-        console.error("[devflow:timing] buildTaskContext TOTAL:", timing["0_total"], "ms");
+        emitSemanticControlLog({
+            event: 'codegraph.selection.completed',
+            identity: {
+                ...logIdentity,
+                contextReceipt: result.taskEnvelope?.receipt.contextHash,
+            },
+            level: warnings.length > 0 ? 'warn' : 'info',
+            timestamp: Date.now(),
+            data: {
+                selectedFiles: result.taskEnvelope?.code.files.length ?? 0,
+                selectedSymbols: result.taskEnvelope?.code.symbols.length ?? 0,
+                rejectedRelations: result.taskEnvelope?.quality.code.rejected ?? 0,
+                ambiguityCount: result.taskEnvelope?.code.ambiguities?.length ?? 0,
+                timing,
+                warnings: warnings.map(value => value.split(':')[0]),
+            },
+        });
         result._timing = timing;
         return result;
     }
@@ -1445,6 +1537,9 @@ export class ContextEngine {
             requestId: options?.requestId,
             host: options?.host,
             command: options?.command,
+            turnId: options?.turnId,
+            intentArtifact: options?.intentArtifact,
+            queryPlan: options?.queryPlan,
             tokenBudget: maxTokens,
             targetAnchors,
             fileRoles: fileRoleByPath,