@devflow-tools/mcp-server 0.17.7 → 0.18.0

package/dist/retrieval-composition.js

@@ -0,0 +1,611 @@
+import { stableRuntimeHash, } from '@devflow-tools/sdk';
+import { openGlobalDevFlowDatabase } from '@devflow-tools/database';
+import { RetrievalCoordinator, RetrievalSessionRepository, RetrievalTaskKernelAdapter, } from '@devflow-tools/retrieval-engine';
+import { TaskEventStore, TaskKernel } from '@devflow-tools/task-runtime';
+import { emitSemanticControlLog, SemanticRuntimeEventProjector } from '@devflow-tools/telemetry';
+import { planDomainAction } from '@devflow-tools/semantic-engine';
+import { createDomainToolRegistry } from './domain-tool-registry.js';
+export { createDomainToolRegistry } from './domain-tool-registry.js';
+export { createSamplingEvidenceReranker } from './sampling-evidence-reranker.js';
+// A task turn has one canonical retrieval receipt. MCP may dispatch the three
+// read-only projections concurrently, so serialize the coordinator execution
+// by the immutable task identity and let every projection reuse its receipt.
+const canonicalRetrievals = new Map();
+const PUBLIC_EVIDENCE_TOP_K = 5;
+export async function executeProjectEvidence(input) {
+    const key = stableRuntimeHash({
+        identity: input.context.identity,
+        taskRevision: input.definition.revision,
+        contextHash: input.context.contextHash,
+        taskDefinitionHash: input.definition.definitionHash,
+        reranker: input.reranker
+            ? { profileId: input.reranker.profileId, profileVersion: input.reranker.profileVersion }
+            : null,
+    });
+    let retrieval = canonicalRetrievals.get(key);
+    if (!retrieval) {
+        retrieval = runCanonicalRetrieval(input);
+        canonicalRetrievals.set(key, retrieval);
+        void retrieval.then(() => {
+            if (canonicalRetrievals.get(key) === retrieval)
+                canonicalRetrievals.delete(key);
+        }, () => {
+            if (canonicalRetrievals.get(key) === retrieval)
+                canonicalRetrievals.delete(key);
+        });
+    }
+    const result = await retrieval;
+    return {
+        envelope: projectCoordinatorResult(input.context, input.query, result.receipt, result.status, result.executionStatus),
+        receipt: result.receipt,
+        status: result.status,
+    };
+}
+async function runCanonicalRetrieval(input) {
+    const database = openGlobalDevFlowDatabase(undefined, { busyTimeoutMs: 500 });
+    try {
+        const coordinator = new RetrievalCoordinator({
+            code: input.engines.codeEvidence,
+            memory: input.engines.memoryQuery,
+            knowledge: input.engines.knowledgeQuery,
+            sessions: new RetrievalSessionRepository(database),
+            taskRuntime: new RetrievalTaskKernelAdapter(new TaskKernel(new TaskEventStore(database), new SemanticRuntimeEventProjector()), input.definition, 'mcp-retrieval-composition'),
+            ...(input.reranker ? { reranker: input.reranker } : {}),
+            observer: semanticRetrievalObserver,
+        });
+        const result = await coordinator.retrieve({
+            context: input.context,
+            taskRevision: input.definition.revision,
+            // The task definition owns the retrieval budget for the whole canonical
+            // turn. Individual MCP projections must not create a second session by
+            // supplying a different host-specific budget.
+            tokenBudget: input.definition.budgets.contextTokens,
+        });
+        recordSelectedEvidence(input.context, result.receipt);
+        return {
+            receipt: result.receipt,
+            status: result.status,
+            executionStatus: result.executionStatus,
+        };
+    }
+    finally {
+        database.close();
+    }
+}
+export async function retrieveProjectEvidence(input) {
+    return (await executeProjectEvidence(input)).envelope;
+}
+function recordSelectedEvidence(context, receipt) {
+    const database = openGlobalDevFlowDatabase(undefined, { busyTimeoutMs: 250 });
+    try {
+        for (const candidate of receipt.selectedEvidence ?? []) {
+            const identity = stableRuntimeHash({
+                requestId: context.identity.requestId,
+                contextHash: context.contextHash,
+                sourceType: candidate.channel,
+                sourceId: candidate.stableRef,
+            });
+            database.appendRetrievalLedgerEvent({
+                id: `retrieval:selected:${identity}`,
+                projectRoot: context.identity.projectRoot,
+                sessionId: context.identity.sessionId,
+                executionId: context.identity.executionId,
+                turnId: context.identity.turnId,
+                requestId: context.identity.requestId,
+                contextReceipt: context.contextHash,
+                sourceType: candidate.channel,
+                sourceId: candidate.stableRef,
+                taskSpecHash: context.taskDefinitionHash,
+                actor: 'mcp:retrieval-composition',
+                sourceVersion: candidate.evidence.sourceRevision,
+                sourceContentHash: candidate.evidence.contentHash,
+                evidenceIds: [candidate.evidence.ref],
+                reasonCode: 'retrieval_selection_completed',
+                stage: 'selected',
+                rank: candidate.rank,
+                finalScore: candidate.score,
+                applicability: arrayStrings(candidate.payload.applicability),
+                toolEvidence: [],
+                payload: {
+                    returnedFinalScore: candidate.score ?? 0,
+                    receiptHash: receipt.receiptHash,
+                    ...releaseEvidenceIdentity(),
+                },
+                createdAt: receipt.createdAt,
+            });
+        }
+    }
+    finally {
+        database.close();
+    }
+}
+function releaseEvidenceIdentity() {
+    const releaseRunId = process.env.DEVFLOW_RELEASE_RUN_ID?.trim();
+    const bundleId = process.env.DEVFLOW_EVALUATION_BUNDLE_ID?.trim();
+    return releaseRunId && bundleId ? { releaseRunId, bundleId } : {};
+}
+export function loadSemanticExecutionContext(input) {
+    if (!input.sessionId || !input.turnId)
+        return null;
+    const database = openGlobalDevFlowDatabase(undefined, { busyTimeoutMs: 250 });
+    try {
+        const latest = database.getLatestSemanticExecutionContext({
+            projectRoot: input.projectRoot, sessionId: input.sessionId, turnId: input.turnId,
+        });
+        if (!latest)
+            return null;
+        const { context, revision } = latest;
+        const snapshot = database.getTaskAggregateSnapshot(input.projectRoot, input.sessionId, input.turnId, revision);
+        const definition = database.getTaskDefinitionV2(context.taskDefinitionHash);
+        const activation = database.getRuntimeActivation(input.projectRoot, input.sessionId, input.turnId, revision);
+        if (!snapshot || !definition || !activation
+            || snapshot.semanticFactsHash !== context.facts.factsHash
+            || snapshot.semanticContextHash !== context.contextHash
+            || snapshot.channelPlanHash !== context.plan.planHash
+            || context.taskDefinitionHash !== definition.definitionHash
+            || context.activationSnapshotHash !== activation.snapshotHash)
+            return null;
+        return { definition, context };
+    }
+    finally {
+        database.close();
+    }
+}
+export function projectDiagnosticCodeResult(result, freshnessMs, input) {
+    const now = Date.now();
+    const requestId = input.requestId;
+    const requiredPaths = new Set(result.requiredFiles.files);
+    const codeFiles = result.selectedEvidence.map(candidate => {
+        const path = String(candidate.payload.path ?? candidate.evidence.sourceId);
+        const required = requiredPaths.has(path);
+        return {
+            ...selectedEvidenceProvenance(candidate, 'code'),
+            rank: candidate.rank,
+            contributingLegs: candidate.contributingLegs,
+            excerpt: selectedEvidenceExcerpt(candidate, candidate.payload.excerpt),
+            path,
+            role: required ? 'target' : 'dependency',
+            artifactRole: required ? 'operation_target' : 'supporting_file',
+            score: candidate.score ?? strengthScore(candidate.strength),
+            symbols: typeof candidate.payload.symbol === 'string' ? [candidate.payload.symbol] : [],
+            evidence: candidate.contributingLegs.map(leg => leg.leg),
+            freshness: {
+                exists: true, indexed: true, current: candidate.freshness?.current ?? true,
+                indexedHash: candidate.evidence.contentHash,
+                currentHash: candidate.evidence.contentHash,
+                ...(candidate.freshness?.reason ? { reason: candidate.freshness.reason } : {}),
+            },
+        };
+    });
+    const envelopeBody = {
+        request: {
+            requestId,
+            turnId: input.turnId,
+            sessionId: input.sessionId,
+            executionId: input.executionId,
+            projectRoot: input.projectRoot,
+            host: input.host,
+            query: input.query,
+            intent: 'unknown',
+            action: 'unknown',
+            requiredPolicyFacets: [], entities: [], symbols: result.keySymbols.map(symbol => symbol.name),
+            knowledgeNeeds: [], targetAnchors: result.requiredFiles.files, projectVersions: {},
+            tokenBudget: Math.max(result.tokenCount, 1),
+        },
+        code: { files: codeFiles, symbols: result.keySymbols.map(symbol => symbol.name) },
+        memory: { entries: [] },
+        knowledge: { entries: [] },
+        quality: {
+            status: 'insufficient',
+            code: { selected: codeFiles.length, rejected: 0, targetHashCurrent: true },
+            memory: { selected: 0, rejected: 0 },
+            knowledge: { selected: 0, rejected: 0, compatibleSources: [] },
+        },
+        allowedFollowups: [],
+        warnings: [{
+                category: 'diagnostic_code_projection',
+                reason: 'Diagnostic Code evidence has no canonical task authority.',
+            }],
+    };
+    const contextHash = stableRuntimeHash(envelopeBody);
+    const taskEnvelope = {
+        ...envelopeBody,
+        receipt: {
+            requestId, issuedAt: now, expiresAt: now + 10 * 60_000,
+            hash: contextHash, contextHash,
+        },
+    };
+    const { selectedEvidence: _selectedEvidence, ...publicResult } = result;
+    return {
+        ...publicResult,
+        authority: 'diagnostic',
+        taskEnvelope,
+        _devflow_unique: {
+            search_method: 'diagnostic_code', task_oriented: false, risk_aware: true,
+            memory_injected: false, knowledge_injected: false, token_estimated: true,
+            required_vs_optional: true,
+        },
+        _accuracy: {
+            data_freshness_ms: freshnessMs, source_layer: 'composite', execution_status: 'executed',
+        },
+    };
+}
+export async function getDiagnosticMemoryResult(memory, options, metadata) {
+    const startedAt = Date.now();
+    const result = await memory.getAll(options);
+    const vectorCoverage = memory.getObservationVectorCoverage();
+    const projected = {
+        ...result,
+        authority: 'diagnostic',
+        _devflow_unique: { memory_version: 1, structured_storage: true, project_context_included: true },
+        _accuracy: {
+            data_freshness_ms: 0, source_layer: 'memory',
+            execution_status: vectorCoverage.missing > 0 ? 'unavailable' : 'executed',
+        },
+    };
+    emitDiagnosticRetrievalLog({
+        metadata, channel: 'memory', selectedCount: result.memories.length,
+        rejectedCount: result.retrieval?.rejectedCount ?? 0,
+        executionStatus: projected._accuracy.execution_status, startedAt, query: options.query,
+        sessionId: options.sessionId, executionId: options.executionId, requestId: options.requestId,
+    });
+    return projected;
+}
+export async function getDiagnosticKnowledgeResult(knowledge, args, metadata) {
+    const startedAt = Date.now();
+    const scope = args.scope?.trim() || 'all';
+    const available = knowledge.getScopes();
+    if (scope !== 'all' && available.length > 0 && !available.includes(scope)) {
+        throw new Error(`Unknown knowledge scope ${JSON.stringify(scope)}. Available scopes: ${available.join(', ')}`);
+    }
+    const options = {
+        ...(scope === 'all' ? {} : { sources: [scope] }),
+        retrievalIntent: 'explicit',
+        ...(args.budgetTokens !== undefined ? { budgetTokens: args.budgetTokens } : {}),
+    };
+    const detailed = await knowledge.searchWithStatus(args.query, options);
+    const projected = {
+        results: detailed.entries, warnings: detailed.warnings,
+        authority: 'diagnostic',
+        budgetTokens: detailed.budgetTokens ?? args.budgetTokens ?? 3_000,
+        tokenCount: detailed.tokenCount, truncatedCount: detailed.truncatedCount ?? 0,
+        rejectedLowScore: detailed.rejectedLowScore,
+        rejectedIncompatibleSources: detailed.rejectedIncompatibleSources,
+        retrievalDiagnostics: detailed.retrievalDiagnostics,
+        _devflow_unique: { source_versioned: true, code_examples_included: true, search_scope: scope },
+        _accuracy: {
+            data_freshness_ms: 0, source_layer: 'knowledge',
+            execution_status: detailed.warnings.length > 0 ? 'unavailable' : 'executed',
+        },
+    };
+    emitDiagnosticRetrievalLog({
+        metadata, channel: 'knowledge', selectedCount: detailed.entries.length,
+        rejectedCount: (detailed.rejectedLowScore ?? 0) + (detailed.rejectedIncompatibleSources ?? 0),
+        executionStatus: projected._accuracy.execution_status, startedAt, query: args.query,
+    });
+    return projected;
+}
+export function projectCoordinatorResult(context, query, receipt, status, executionStatus) {
+    const evidence = (receipt.selectedEvidence ?? []).filter((candidate) => {
+        const channelCount = (receipt.selectedEvidence ?? [])
+            .filter((item) => item.channel === candidate.channel)
+            .indexOf(candidate);
+        return channelCount < PUBLIC_EVIDENCE_TOP_K;
+    });
+    const code = evidence.filter(item => item.channel === 'code');
+    const memory = evidence.filter(item => item.channel === 'memory');
+    const knowledge = evidence.filter(item => item.channel === 'knowledge');
+    const required = code.filter(item => item.strength === 'strong');
+    const optional = code.filter(item => item.strength !== 'strong');
+    const activeSkill = context.scopeBindings.skill?.id;
+    const primaryIntent = context.facts.intents[0] ?? 'unknown';
+    const primaryAction = context.facts.actions[0] ?? 'analyze';
+    const registry = createDomainToolRegistry(activeSkill);
+    const targetStateEvidence = buildTargetStateEvidence(context, required);
+    const objectKind = primaryIntent === 'performance'
+        ? 'performance'
+        : activeSkill === 'devflow:react' && ['create', 'modify'].includes(primaryAction)
+            ? 'component' : undefined;
+    const actionPlan = registry.tools.length > 0
+        ? planDomainAction({
+            identity: context.identity,
+            taskRevisionHash: context.taskDefinitionHash,
+            taskDefinitionHash: context.taskDefinitionHash,
+            semanticContextHash: context.contextHash,
+            facts: context.facts,
+            actionAuthority: context.actionAuthority,
+            objectKind,
+            activeSkill,
+            registry,
+            targetStateEvidence,
+            phase: 'final',
+        }) : undefined;
+    const toolDefinition = actionPlan?.selectedTool
+        ? registry.tools.find(tool => tool.tool === actionPlan.selectedTool) : undefined;
+    const actionInput = toolDefinition ? buildCanonicalActionInput(toolDefinition.tool, context) : undefined;
+    const canonicalAction = actionPlan?.status === 'selected' && toolDefinition && actionInput
+        ? buildCanonicalAction({ context, receipt, actionPlan, toolDefinition, input: actionInput })
+        : undefined;
+    if (actionPlan) {
+        emitSemanticControlLog({
+            event: actionPlan.status === 'selected' ? 'domain.action.planned'
+                : actionPlan.status === 'needs_condition_evidence' ? 'domain.action.conditional'
+                    : actionPlan.status === 'conflicted' ? 'domain.action.conflicted' : 'domain.action.abstained',
+            identity: { ...context.identity, actionReceipt: actionPlan.planHash },
+            level: actionPlan.status === 'selected' ? 'info' : 'warn', timestamp: Date.now(),
+            data: {
+                status: actionPlan.status, reasonCode: actionPlan.reasonCode,
+                selectedTool: actionPlan.selectedTool, registryHash: actionPlan.registryHash,
+                candidateCount: actionPlan.candidates.length,
+            },
+        });
+        emitSemanticControlLog({
+            event: 'canonical.tool.resolved',
+            identity: { ...context.identity, actionReceipt: actionPlan.planHash },
+            level: actionPlan.status === 'selected' ? 'info' : 'warn',
+            timestamp: Date.now(),
+            data: {
+                status: actionPlan.status,
+                reasonCode: actionPlan.reasonCode,
+                selectedTool: actionPlan.selectedTool,
+                registryHash: actionPlan.registryHash,
+                candidateCount: actionPlan.candidates.length,
+            },
+        });
+    }
+    const taskEnvelope = {
+        request: {
+            requestId: context.identity.requestId, turnId: context.identity.turnId,
+            sessionId: context.identity.sessionId, executionId: context.identity.executionId,
+            projectRoot: context.identity.projectRoot, host: context.identity.hostId, query,
+            intent: primaryIntent, action: primaryAction,
+            requiredPolicyFacets: [], entities: context.facts.entities,
+            symbols: context.plan.code.requirement === 'prohibited' ? [] : context.plan.code.typedQuery.symbols,
+            knowledgeNeeds: context.facts.knowledgeNeeds,
+            targetAnchors: context.facts.targets, projectVersions: {}, tokenBudget: 8_000,
+            queryPlanHash: context.plan.planHash,
+        },
+        code: {
+            files: code.map(item => ({
+                ...selectedEvidenceProvenance(item, 'code'),
+                rank: item.rank,
+                contributingLegs: item.contributingLegs,
+                excerpt: selectedEvidenceExcerpt(item, item.payload.excerpt),
+                path: String(item.payload.path ?? item.evidence.sourceId),
+                role: item.strength === 'strong' ? 'target' : 'dependency',
+                artifactRole: item.strength === 'strong' ? 'operation_target' : 'supporting_file',
+                score: item.score ?? strengthScore(item.strength),
+                symbols: typeof item.payload.symbol === 'string' ? [item.payload.symbol] : [],
+                evidence: item.contributingLegs.map(leg => leg.leg),
+                freshness: {
+                    exists: true, indexed: true, current: item.freshness?.current ?? true,
+                    ...(item.evidence.contentHash ? {
+                        indexedHash: item.evidence.contentHash,
+                        currentHash: item.evidence.contentHash,
+                    } : {}),
+                    ...(item.freshness?.reason ? { reason: item.freshness.reason } : {}),
+                },
+            })),
+            symbols: code.flatMap(item => typeof item.payload.symbol === 'string' ? [item.payload.symbol] : []),
+        },
+        memory: { entries: memory.map(item => ({
+                ...selectedEvidenceProvenance(item, 'memory'),
+                rank: item.rank,
+                contributingLegs: item.contributingLegs,
+                id: String(item.payload.id ?? item.evidence.sourceId), title: String(item.payload.title ?? ''),
+                excerpt: selectedEvidenceExcerpt(item, item.payload.content ?? item.payload.title),
+                type: String(item.payload.type ?? 'unknown'), score: item.score ?? 0,
+                applicability: arrayStrings(item.payload.applicability),
+                evidenceStatus: item.payload.evidenceStatus === 'verified' ? 'verified' : 'unverified',
+            })) },
+        knowledge: { entries: knowledge.map(item => ({
+                ...selectedEvidenceProvenance(item, 'knowledge'),
+                rank: item.rank,
+                contributingLegs: item.contributingLegs,
+                id: String(item.payload.id ?? item.evidence.sourceId), source: String(item.payload.source ?? ''),
+                title: String(item.payload.title ?? ''), excerpt: selectedEvidenceExcerpt(item, item.payload.excerpt),
+                url: String(item.payload.url ?? ''),
+                ...(typeof item.payload.version === 'string' ? { version: item.payload.version } : {}),
+                score: item.score ?? 0, applicability: arrayStrings(item.payload.applicability),
+            })) },
+        quality: {
+            status: status === 'sufficient' ? 'healthy' : 'insufficient',
+            code: { selected: code.length, rejected: receipt.rejectedRefs.length, targetHashCurrent: required.every(item => item.freshness?.current) },
+            memory: { selected: memory.length, rejected: 0 },
+            knowledge: { selected: knowledge.length, rejected: 0, compatibleSources: [...new Set(knowledge.map(item => String(item.payload.source ?? '')))] },
+        },
+        allowedFollowups: receipt.gaps.map(gap => ({ kind: gap.kind, target: gap.target, reason: gap.reason })),
+        ...(canonicalAction ? { canonicalNextAction: canonicalAction } : {}),
+        warnings: [
+            ...receipt.gaps.map(gap => ({ category: gap.kind, reason: gap.reason })),
+            ...(actionPlan && actionPlan.status !== 'selected'
+                ? [{ category: `domain_action_${actionPlan.status}`, reason: actionPlan.reasonCode }]
+                : []),
+        ],
+        receipt: {
+            requestId: context.identity.requestId, issuedAt: receipt.createdAt,
+            expiresAt: receipt.createdAt + 10 * 60_000, hash: receipt.receiptHash,
+            contextHash: context.contextHash, queryPlanHash: context.plan.planHash,
+        },
+    };
+    const reasoning = code.map(item => ({
+        source: 'dependency_trace',
+        fileGroup: String(item.payload.path ?? item.evidence.sourceId),
+        explanation: `${item.strength} evidence: ${item.contributingLegs.map(leg => leg.leg).join(', ')}`,
+    }));
+    return {
+        authority: 'authoritative_task',
+        _devflow_evidence_refs: evidence.map(item => item.stableRef),
+        taskType: legacyTaskType(primaryIntent),
+        requiredFiles: group(required, reasoning), optionalFiles: group(optional, reasoning),
+        keySymbols: code.flatMap(item => typeof item.payload.symbol === 'string' ? [{
+                name: item.payload.symbol, file: String(item.payload.path ?? ''),
+                kind: String(item.payload.kind ?? 'unknown'), relevance: item.strength === 'strong' ? 'direct' : 'indirect',
+            }] : []),
+        graphSummary: { roots: required.map(item => item.evidence.sourceId), traversalDepth: context.plan.code.requirement === 'prohibited' ? 0 : context.plan.code.typedQuery.maxDepth, relatedNodeCount: code.length },
+        riskHints: [], nextActions: [], reasoning,
+        confidence: code.some(item => item.strength === 'strong') ? 0.9 : code.length > 0 ? 0.5 : 0,
+        tokenCount: evidence.reduce((sum, item) => sum + (item.estimatedTokens ?? 0), 0),
+        warnings: receipt.gaps.map(gap => gap.reason), taskEnvelope,
+        _devflow_unique: {
+            search_method: receipt.reranker ? 'rrf_reranker' : 'rrf', task_oriented: true,
+            risk_aware: true, memory_injected: memory.length > 0, knowledge_injected: knowledge.length > 0,
+            token_estimated: true, required_vs_optional: true,
+        },
+        _accuracy: {
+            data_freshness_ms: 0, source_layer: 'composite',
+            execution_status: executionStatus,
+        },
+    };
+}
+function buildTargetStateEvidence(context, targets) {
+    return context.facts.targets.flatMap(anchor => {
+        const matched = targets.find(item => String(item.payload.path ?? '') === anchor);
+        if (!matched)
+            return [];
+        const body = {
+            schemaVersion: 'target-state-evidence.v1',
+            taskRevisionHash: context.taskDefinitionHash,
+            semanticContextHash: context.contextHash,
+            targetAnchor: anchor,
+            state: 'existing',
+            authority: 'code_receipt',
+            evidenceIds: [matched.stableRef],
+        };
+        return [{ ...body, evidenceHash: stableRuntimeHash(body) }];
+    });
+}
+function buildCanonicalActionInput(tool, context) {
+    const target = context.facts.targets[0]
+        ?? (context.plan.code.requirement === 'prohibited' ? undefined : context.plan.code.typedQuery.targetAnchors[0]);
+    const componentName = context.facts.entities.find(entity => /^[A-Z][A-Za-z0-9_$]*$/u.test(entity))
+        ?? target?.split('/').pop()?.replace(/\.[^.]+$/u, '')
+        ?? 'Component';
+    return {
+        projectRoot: context.identity.projectRoot,
+        ...(target && ['react_refactor_component', 'react_audit_performance'].includes(tool) ? { filePath: target } : {}),
+        ...(tool === 'react_new_component' ? { componentName } : {}),
+    };
+}
+function buildCanonicalAction(input) {
+    const { context, receipt, actionPlan, toolDefinition } = input;
+    const required = context.actionAuthority.mutation === 'authorized';
+    const action = context.facts.actions[0] ?? 'unknown';
+    const operationMode = ['create', 'modify', 'delete', 'analyze', 'debug', 'format'].includes(action)
+        ? action : 'unknown';
+    return {
+        tool: toolDefinition.tool,
+        projectedTool: context.identity.hostId === 'claude-code' ? `mcp__devflow__${toolDefinition.tool}` : toolDefinition.tool,
+        input: input.input,
+        status: required ? 'required' : 'recommended',
+        required,
+        reason: actionPlan.reasonCode,
+        binding: {
+            projectRoot: context.identity.projectRoot,
+            sessionId: context.identity.sessionId,
+            executionId: context.identity.executionId,
+            requestId: context.identity.requestId,
+            turnId: context.identity.turnId,
+            queryPlanHash: context.plan.planHash,
+            domainActionPlanHash: actionPlan.planHash,
+            ...(context.scopeBindings.skill ? { activeSkill: context.scopeBindings.skill.id } : {}),
+            targetAnchors: context.facts.targets,
+            requiredContextReceipt: receipt.receiptHash,
+            requiredPolicyFacets: [],
+            operationMode,
+            normalizedInputHash: stableRuntimeHash(input.input),
+            operationTargets: context.facts.targets.map(path => ({
+                path, expectedState: toolDefinition.targetState === 'existing' ? 'existing' : 'unknown',
+            })),
+        },
+        verificationPlan: toolDefinition.verification,
+    };
+}
+const semanticRetrievalObserver = {
+    record(event) {
+        emitSemanticControlLog({
+            event: event.name, identity: event.identity,
+            level: event.name === 'retrieval.cycle.stopped' && event.data.sufficiency !== 'sufficient' ? 'warn' : 'info',
+            data: event.data, timestamp: event.timestamp,
+        });
+    },
+};
+function strengthScore(value) {
+    return value === 'strong' ? 1 : value === 'supporting' ? 0.65 : 0.3;
+}
+function selectedEvidenceProvenance(candidate, channel) {
+    const sourceRevision = candidate.evidence.sourceRevision;
+    const contentHash = candidate.evidence.contentHash;
+    const retrievalProfile = candidate.retrievalProfile;
+    const generation = candidate.generation;
+    const vectorEvidence = candidate.contributingLegs.some(leg => leg.leg.endsWith(':vector'));
+    if (candidate.channel !== channel) {
+        throw new Error(`SELECTED_EVIDENCE_CHANNEL_MISMATCH:${candidate.stableRef}`);
+    }
+    if (!sourceRevision || !contentHash
+        || vectorEvidence && (!retrievalProfile || generation === undefined)
+        || Boolean(retrievalProfile) !== (generation !== undefined)
+        || generation !== undefined && (!Number.isSafeInteger(generation) || generation < 1)) {
+        throw new Error(`SELECTED_EVIDENCE_PROVENANCE_INCOMPLETE:${candidate.stableRef}`);
+    }
+    return {
+        channel, stableRef: candidate.stableRef, sourceRevision, contentHash,
+        ...(retrievalProfile && generation !== undefined ? { retrievalProfile, generation } : {}),
+        provenanceStatus: 'complete',
+        provenance: {
+            sourceId: candidate.evidence.sourceId,
+            producer: candidate.evidence.producer,
+            producerVersion: candidate.evidence.producerVersion,
+            parentRefs: candidate.evidence.parentRefs,
+        },
+    };
+}
+function arrayStrings(value) {
+    return Array.isArray(value) ? value.map(String) : [];
+}
+function boundedExcerpt(value) {
+    return typeof value === 'string' ? value.slice(0, 2_000) : '';
+}
+function selectedEvidenceExcerpt(candidate, value) {
+    const excerpt = boundedExcerpt(value);
+    if (!excerpt.trim()) {
+        throw new Error(`SELECTED_EVIDENCE_EXCERPT_MISSING:${candidate.stableRef}`);
+    }
+    return excerpt;
+}
+function emitDiagnosticRetrievalLog(input) {
+    emitSemanticControlLog({
+        event: 'retrieval.diagnostic.completed',
+        identity: {
+            projectRoot: input.metadata.projectRoot,
+            sessionId: input.sessionId,
+            executionId: input.executionId,
+            requestId: input.requestId,
+        },
+        level: input.executionStatus === 'executed' ? 'info' : 'warn',
+        timestamp: Date.now(),
+        data: {
+            authority: 'diagnostic',
+            channel: input.channel,
+            adapter: input.metadata.adapter,
+            selectedCount: input.selectedCount,
+            rejectedCount: input.rejectedCount,
+            executionStatus: input.executionStatus,
+            durationMs: Date.now() - input.startedAt,
+            ...(input.query ? { queryHash: stableRuntimeHash({ query: input.query }) } : {}),
+        },
+    });
+}
+function legacyTaskType(value) {
+    return ['debug', 'feature', 'refactor', 'understand', 'review'].includes(value)
+        ? value : 'unknown';
+}
+function group(values, reasoning) {
+    const files = [...new Set(values.map(item => String(item.payload.path ?? item.evidence.sourceId)))];
+    return {
+        files,
+        symbols: values.flatMap(item => typeof item.payload.symbol === 'string' ? [item.payload.symbol] : []),
+        reasoning: reasoning.filter(item => files.includes(item.fileGroup)),
+    };
+}
+//# sourceMappingURL=retrieval-composition.js.map