@devflow-tools/retrieval-engine 0.18.0

package/dist/retrieval-coordinator.js

@@ -0,0 +1,778 @@
+import { stableRuntimeHash, } from '@devflow-tools/sdk';
+import { packEvidence } from './packing.js';
+import { reciprocalRankFusion } from './rrf.js';
+import { decideSufficiency } from './sufficiency.js';
+import { RETRIEVAL_COORDINATOR_VERSION } from './retrieval-session.js';
+const RERANKER_POOL_LIMIT = 20;
+export class RetrievalCoordinator {
+    options;
+    version;
+    constructor(options) {
+        this.options = options;
+        this.version = options.coordinatorVersion ?? RETRIEVAL_COORDINATOR_VERSION;
+    }
+    async retrieve(input) {
+        const now = input.now ?? Date.now();
+        const session = this.options.sessions.open({
+            context: input.context,
+            taskRevision: input.taskRevision,
+            tokenBudget: input.tokenBudget ?? executableChannelCount(input.context) * 2_000 + 2_000,
+            coordinatorVersion: this.version,
+            now,
+        });
+        const priorCycles = this.options.sessions.cycles(session.id);
+        await this.options.taskRuntime.sessionOpened({
+            identity: input.context.identity,
+            taskRevision: input.taskRevision,
+            sessionId: session.id,
+            factsHash: input.context.facts.factsHash,
+            planHash: session.planHash,
+            activationSnapshotHash: session.activationSnapshotHash,
+            coordinatorVersion: this.version,
+        });
+        for (const priorCycle of priorCycles)
+            await this.options.taskRuntime.cycleCompleted({
+                identity: input.context.identity,
+                taskRevision: input.taskRevision,
+                cycle: priorCycle,
+                terminal: session.state !== 'open' && priorCycle.cycle === session.cycle,
+            });
+        if (priorCycles.length === 0) {
+            this.observe('retrieval.session.opened', input.context, now, {
+                sessionId: session.id,
+                taskRevision: input.taskRevision,
+                factsHash: input.context.facts.factsHash,
+                planHash: session.planHash,
+                activationSnapshotHash: session.activationSnapshotHash,
+                coordinatorVersion: this.version,
+                tokenBudget: session.initialTokenBudget,
+            });
+        }
+        if (session.state !== 'open') {
+            const latest = priorCycles.at(-1);
+            if (!latest)
+                throw new Error('RETRIEVAL_TERMINAL_RECEIPT_MISSING');
+            return {
+                status: latest.sufficiency,
+                executionStatus: latest.executionStatus,
+                receipt: latest.compositeReceipt,
+                cycles: priorCycles,
+            };
+        }
+        const signatures = requestSignatures(input.context, input.taskRevision, priorCycles.at(-1)?.gaps ?? []);
+        const completedSignatures = new Set(priorCycles.flatMap(cycle => cycle.requestSignatures.map(signature => signature.signatureHash)));
+        const activeSignatures = signatures.filter(signature => !completedSignatures.has(signature.signatureHash));
+        const settled = await Promise.allSettled(activeSignatures.map(async (signature) => {
+            const producer = signature.channel === 'code' ? this.options.code
+                : signature.channel === 'memory' ? this.options.memory : this.options.knowledge;
+            const result = await producer.search(input.context, signature);
+            return { signature, result: validateProducerResult(signature, input.context, result) };
+        }));
+        const outputs = settled.map((entry, index) => entry.status === 'fulfilled'
+            ? { ...entry.value, failureStatus: undefined }
+            : {
+                signature: activeSignatures[index],
+                result: unavailable(activeSignatures[index].channel, input.context, providerFailureReason(entry.reason), now, activeSignatures[index]),
+                failureStatus: 'failed',
+            });
+        const currentAvailability = aggregateChannelAvailability(outputs);
+        const legs = outputs.map(output => legOutcome(output.signature, output.result, output.failureStatus));
+        const candidateReceipts = outputs.flatMap(output => output.result.candidates.map(candidate => evidenceStageReceipt(candidate, 'candidate', [output.result.receipt.receiptId], now)));
+        const rejected = [];
+        const eligible = outputs.flatMap(output => hardFilter(output.result.candidates.map(candidate => scopeCandidateLegs(output.signature, candidate)), output.signature.channel, input.context, rejected, now));
+        const eligibleRefs = new Set(eligible.map(candidate => candidate.stableRef));
+        const eligibilityReceipts = candidateReceipts.map(receipt => eligibleRefs.has(receipt.stableRef)
+            ? evidenceStageReceiptFrom(receipt, 'eligible', now)
+            : evidenceStageReceiptFrom(receipt, 'rejected', now, rejected.find(item => item.ref === receipt.stableRef)?.reason ?? 'ineligible'));
+        let fused = reciprocalRankFusion(eligible);
+        const fusedCount = fused.length;
+        let rerankerFailed = false;
+        let rerankerReceipt;
+        if (this.options.reranker && fused.length > 0) {
+            const pool = fused.slice(0, RERANKER_POOL_LIMIT);
+            const requestHash = stableRuntimeHash({
+                contextHash: input.context.contextHash,
+                candidates: pool.map(item => item.candidate.stableRef),
+                profileId: this.options.reranker.profileId,
+                profileVersion: this.options.reranker.profileVersion,
+            });
+            const startedAt = performance.now();
+            try {
+                for (const item of fused.slice(RERANKER_POOL_LIMIT)) {
+                    rejected.push({ ref: item.candidate.stableRef, reason: 'reranker_pool_limit' });
+                }
+                fused = pool;
+                const reranked = await this.options.reranker.rerank({
+                    context: input.context,
+                    candidates: pool.map(item => item.candidate),
+                });
+                const poolRefs = new Set(pool.map(item => item.candidate.stableRef));
+                const scores = new Map();
+                for (const item of reranked) {
+                    if (!poolRefs.has(item.stableRef) || scores.has(item.stableRef) || !Number.isFinite(item.score)) {
+                        throw new Error('RERANKER_RESULT_INVALID');
+                    }
+                    scores.set(item.stableRef, item.score);
+                }
+                fused = [...pool].sort((left, right) => Number(scores.has(right.candidate.stableRef)) - Number(scores.has(left.candidate.stableRef))
+                    || (scores.get(right.candidate.stableRef) ?? 0) - (scores.get(left.candidate.stableRef) ?? 0)
+                    || right.rrfScore - left.rrfScore
+                    || left.candidate.stableRef.localeCompare(right.candidate.stableRef));
+                rerankerReceipt = providerReceipt({
+                    executionKey: `${session.id}:${session.cycle + 1}:reranker`, requestHash,
+                    providerId: this.options.reranker.profileId,
+                    providerVersion: this.options.reranker.profileVersion,
+                    status: 'ready', proposalCount: pool.length, acceptedCount: scores.size,
+                    rejectedCount: pool.length - scores.size, reasonCodes: [],
+                    latencyMs: performance.now() - startedAt, createdAt: now,
+                });
+                this.observe('provider.execution.completed', input.context, now, providerLogData(rerankerReceipt));
+            }
+            catch (error) {
+                rerankerFailed = true;
+                fused = [];
+                const invalid = error instanceof Error && error.message === 'RERANKER_RESULT_INVALID';
+                rerankerReceipt = providerReceipt({
+                    executionKey: `${session.id}:${session.cycle + 1}:reranker`, requestHash,
+                    providerId: this.options.reranker.profileId,
+                    providerVersion: this.options.reranker.profileVersion,
+                    status: invalid ? 'invalid' : 'unavailable', proposalCount: pool.length,
+                    acceptedCount: 0, rejectedCount: pool.length,
+                    reasonCodes: [invalid ? 'reranker_result_invalid' : 'reranker_exception'],
+                    latencyMs: performance.now() - startedAt, createdAt: now,
+                });
+                this.observe('provider.execution.rejected', input.context, now, providerLogData(rerankerReceipt));
+            }
+        }
+        const previousReceipt = priorCycles.at(-1)?.compositeReceipt;
+        const activeChannels = new Set(activeSignatures.map(signature => signature.channel));
+        const gaps = dedupeGaps([
+            ...(previousReceipt?.gaps ?? []).filter(gap => gap.resolver === 'none' || !activeChannels.has(gap.resolver)),
+            ...outputs.flatMap(output => currentAvailability[output.signature.channel] !== 'unavailable'
+                && output.result.availability === 'unavailable' ? [] : output.result.gaps),
+            ...(rerankerFailed ? [{
+                    kind: 'unavailable_channel',
+                    reason: 'reranker_unavailable',
+                    evidenceRefs: [],
+                    resolver: 'none',
+                    priority: 1,
+                }] : []),
+        ]);
+        this.observe('retrieval.fusion.completed', input.context, now, {
+            sessionId: session.id,
+            cycle: session.cycle + 1,
+            candidateCount: outputs.reduce((sum, output) => sum + output.result.candidates.length, 0),
+            eligibleCount: eligible.length,
+            fusedCount,
+            rejectedCount: rejected.length,
+            contributingLegCount: new Set(eligible.flatMap(candidate => candidate.contributingLegs.map(leg => leg.leg))).size,
+            coordinatorVersion: this.version,
+            rerankerProfile: this.options.reranker
+                ? `${this.options.reranker.profileId}@${this.options.reranker.profileVersion}` : 'none',
+            rerankerStatus: rerankerReceipt?.status ?? 'not_configured',
+        });
+        const packed = packEvidence({
+            context: input.context,
+            fused,
+            rejected,
+            gaps,
+            tokenBudget: session.remainingTokenBudget,
+            coordinatorVersion: this.version,
+            parentReceiptIds: [
+                ...outputs.map(output => output.result.receipt.receiptId),
+                ...(rerankerReceipt ? [rerankerReceipt.receiptId] : []),
+            ],
+            createdAt: now,
+        });
+        const eligibleReceiptIds = evidenceReceiptIdsByRef(eligibilityReceipts.filter(receipt => receipt.stage === 'eligible'));
+        const rankedReceipts = fused.map((item, index) => evidenceStageReceipt(item.candidate, 'ranked', eligibleReceiptIds.get(item.candidate.stableRef) ?? [], now, undefined, index + 1));
+        const rankedReceiptIds = evidenceReceiptIdsByRef(rankedReceipts);
+        const candidateReceiptIds = evidenceReceiptIdsByRef(candidateReceipts);
+        const terminalReceipts = [
+            ...packed.selected.map((candidate, index) => evidenceStageReceipt(candidate, 'selected', rankedReceiptIds.get(candidate.stableRef)
+                ?? eligibleReceiptIds.get(candidate.stableRef)
+                ?? candidateReceiptIds.get(candidate.stableRef)
+                ?? [], now, undefined, index + 1)),
+            ...rejected.flatMap(item => {
+                const candidate = outputs.flatMap(output => output.result.candidates)
+                    .find(value => value.stableRef === item.ref);
+                return candidate ? [evidenceStageReceipt(candidate, 'rejected', rankedReceiptIds.get(item.ref)
+                        ?? eligibleReceiptIds.get(item.ref)
+                        ?? candidateReceiptIds.get(item.ref)
+                        ?? [], now, item.reason)] : [];
+            }),
+        ];
+        const cycleEvidenceReceipts = dedupeEvidenceStageReceipts([
+            ...candidateReceipts,
+            ...eligibilityReceipts,
+            ...rankedReceipts,
+            ...terminalReceipts,
+        ]);
+        const previousRefs = new Set(priorCycles.flatMap(cycle => cycle.selectedRefs));
+        const stableRefGain = packed.receipt.selectedRefs.filter(ref => !previousRefs.has(ref)).length;
+        const noGainCount = stableRefGain > 0 ? 0 : Math.min(2, (priorCycles.at(-1)?.noGainCount ?? 0) + 1);
+        const availability = {
+            ...(previousReceipt?.channelAvailability ?? {}),
+            ...currentAvailability,
+        };
+        const cumulativeSelectedRefs = dedupeStrings([
+            ...(previousReceipt?.selectedRefs ?? []),
+            ...packed.receipt.selectedRefs,
+        ]);
+        const selectedCounts = Object.fromEntries(['code', 'memory', 'knowledge'].map(channel => [
+            channel, channel === 'code' && requiresStrongCodeEvidence(input.context)
+                ? mergeSelectedEvidence(previousReceipt?.selectedEvidence, packed.receipt.selectedEvidence)
+                    .filter(candidate => candidate.channel === 'code' && candidate.strength === 'strong').length
+                : new Set([
+                    ...(previousReceipt?.selectedRefsByChannel?.[channel] ?? []),
+                    ...(packed.receipt.selectedRefsByChannel?.[channel] ?? []),
+                ]).size,
+        ]));
+        let sufficiency = decideSufficiency({ context: input.context, availability, selectedCounts, gaps });
+        if (activeSignatures.length === 0 || noGainCount >= 2) {
+            sufficiency = gaps.some(gap => gap.kind === 'unavailable_channel') ? 'gap_unavailable' : 'abstain';
+        }
+        const cumulativeRejectedRefs = dedupeRejected([
+            ...(previousReceipt?.rejectedRefs ?? []),
+            ...rejected,
+        ]);
+        if (rejected.length > 0) {
+            this.observe('retrieval.candidate.rejected', input.context, now, {
+                sessionId: session.id,
+                cycle: session.cycle + 1,
+                rejectedCount: rejected.length,
+                reasonCounts: rejectionReasonCounts(rejected),
+                coordinatorVersion: this.version,
+            });
+        }
+        const executionStatus = retrievalExecutionStatus({
+            legs,
+            rawCandidateCount: outputs.reduce((sum, output) => sum + producerCandidateCount(output.result), 0),
+            eligibleCount: eligible.length,
+            rerankerFailed,
+        });
+        const compositeBody = {
+            ...packed.receipt,
+            parentReceiptIds: dedupeStrings([
+                ...(previousReceipt ? [previousReceipt.receiptId] : []),
+                ...legs.map(leg => leg.legId),
+                ...terminalReceipts.map(receipt => receipt.receiptId),
+                ...(rerankerReceipt ? [rerankerReceipt.receiptId] : []),
+            ]).sort(),
+            selectedRefs: cumulativeSelectedRefs,
+            selectedEvidence: mergeSelectedEvidence(previousReceipt?.selectedEvidence, packed.receipt.selectedEvidence),
+            rejectedRefs: cumulativeRejectedRefs,
+            contributingLegs: mergeContributingLegs(previousReceipt?.contributingLegs, packed.receipt.contributingLegs),
+            channelAvailability: availability,
+            selectedRefsByChannel: mergeSelectedRefsByChannel(previousReceipt?.selectedRefsByChannel, packed.receipt.selectedRefsByChannel),
+            legs: mergeLegOutcomes(previousReceipt?.legs, legs),
+            evidenceReceipts: dedupeEvidenceStageReceipts([
+                ...(previousReceipt?.evidenceReceipts ?? []),
+                ...cycleEvidenceReceipts,
+            ]),
+            ...(this.options.reranker ? {
+                reranker: {
+                    profileId: this.options.reranker.profileId,
+                    profileVersion: this.options.reranker.profileVersion,
+                    ...(rerankerReceipt ?? previousReceipt?.reranker?.providerReceipt
+                        ? { providerReceipt: (rerankerReceipt ?? previousReceipt?.reranker?.providerReceipt) }
+                        : {}),
+                },
+            } : {}),
+        };
+        const { receiptHash: _packedReceiptHash, ...unhashedComposite } = compositeBody;
+        const compositeReceipt = {
+            ...unhashedComposite,
+            receiptHash: stableRuntimeHash(unhashedComposite),
+        };
+        const cycleBody = {
+            schemaVersion: 'retrieval-cycle-receipt.v1',
+            sessionId: session.id,
+            cycle: session.cycle + 1,
+            requestSignatures: activeSignatures,
+            legs,
+            selectedRefs: packed.receipt.selectedRefs,
+            rejectedRefs: rejected,
+            gaps,
+            tokenCost: packed.tokenCost,
+            stableRefGain,
+            noGainCount,
+            sufficiency,
+            executionStatus,
+            compositeReceipt,
+            evidenceHash: stableRuntimeHash({ selected: cumulativeSelectedRefs, gaps }),
+            createdAt: now,
+        };
+        const cycle = {
+            ...cycleBody,
+            receiptHash: stableRuntimeHash(cycleBody),
+        };
+        const persistedSession = this.options.sessions.append(session, cycle, session.remainingTokenBudget - packed.tokenCost);
+        await this.options.taskRuntime.cycleCompleted({
+            identity: input.context.identity,
+            taskRevision: input.taskRevision,
+            cycle,
+            terminal: persistedSession.state !== 'open',
+        });
+        this.observe('retrieval.cycle.completed', input.context, now, {
+            sessionId: session.id,
+            cycle: cycle.cycle,
+            receiptId: cycle.compositeReceipt.receiptId,
+            receiptHash: cycle.compositeReceipt.receiptHash,
+            selectedCount: cycle.selectedRefs.length,
+            rejectedCount: cycle.rejectedRefs.length,
+            gapCount: cycle.gaps.length,
+            stableRefGain: cycle.stableRefGain,
+            noGainCount: cycle.noGainCount,
+            tokenCost: cycle.tokenCost,
+            sufficiency: cycle.sufficiency,
+            coordinatorVersion: this.version,
+        });
+        this.observe('retrieval.selection.completed', input.context, now, {
+            sessionId: session.id,
+            cycle: cycle.cycle,
+            receiptId: cycle.compositeReceipt.receiptId,
+            receiptHash: cycle.compositeReceipt.receiptHash,
+            selectedCount: cycle.compositeReceipt.selectedRefs.length,
+            rejectedCount: cycle.compositeReceipt.rejectedRefs.length,
+            gapCount: cycle.compositeReceipt.gaps.length,
+            sufficiency: cycle.sufficiency,
+            coordinatorVersion: this.version,
+        });
+        if (persistedSession.state !== 'open') {
+            this.observe('retrieval.cycle.stopped', input.context, now, {
+                sessionId: session.id,
+                cycle: cycle.cycle,
+                reason: stopReason(cycle, session.remainingTokenBudget - packed.tokenCost),
+                sufficiency: cycle.sufficiency,
+                receiptHash: cycle.compositeReceipt.receiptHash,
+            });
+        }
+        return {
+            status: sufficiency,
+            executionStatus,
+            receipt: cycle.compositeReceipt,
+            cycles: [...priorCycles, cycle],
+        };
+    }
+    observe(name, context, timestamp, data) {
+        try {
+            this.options.observer?.record({ name, identity: context.identity, data, timestamp });
+        }
+        catch { }
+    }
+}
+function requestSignatures(context, taskRevision, openGaps) {
+    return ['code', 'memory', 'knowledge'].flatMap(channel => {
+        const channelPlan = context.plan[channel];
+        const channelGaps = openGaps.filter(gap => gap.resolver === channel)
+            .map(gap => ({
+            kind: gap.kind,
+            reasonCode: gap.reason,
+            ...(gap.target ? { target: gap.target } : {}),
+            evidenceRefs: [...gap.evidenceRefs].sort(),
+            priority: gap.priority,
+        }));
+        if (channelPlan.requirement === 'prohibited')
+            return [];
+        const typedQueryBase = channelGaps.length > 0
+            ? { planQuery: channelPlan.typedQuery, openGaps: channelGaps }
+            : { planQuery: channelPlan.typedQuery };
+        const embeddingPurpose = channel === 'code' ? 'code_retrieval'
+            : channel === 'memory' ? 'memory_retrieval' : 'knowledge_retrieval';
+        const scopeKinds = channel === 'memory'
+            ? new Set(context.plan.memory.requirement === 'prohibited' ? [] : context.plan.memory.typedQuery.scopes)
+            : new Set(['project']);
+        const scopes = [context.scopeBindings.project, context.scopeBindings.session, context.scopeBindings.skill]
+            .filter((scope) => Boolean(scope) && scopeKinds.has(scope.kind));
+        const minimumAuthority = channel === 'knowledge' && context.plan.knowledge.requirement !== 'prohibited'
+            ? context.plan.knowledge.typedQuery.minimumAuthority : undefined;
+        const filters = {
+            scopes,
+            embeddingPurpose,
+            ...(context.embeddingProfiles[embeddingPurpose]
+                ? { embeddingProfileHash: context.embeddingProfiles[embeddingPurpose] }
+                : {}),
+            ...(minimumAuthority !== undefined ? { minimumAuthority } : {}),
+        };
+        const variants = validateQueryVariants(channel, context.facts.sourceHash, [channelPlan.original, ...channelPlan.additions]);
+        return variants.map(queryVariant => {
+            const typedQuery = { ...typedQueryBase, queryVariant };
+            const body = {
+                schemaVersion: 'retrieval-request-signature.v1',
+                parentReceiptIds: [],
+                channel,
+                identity: context.identity,
+                taskRevision,
+                factsHash: context.facts.factsHash,
+                planHash: context.plan.planHash,
+                activationSnapshotHash: context.activationSnapshotHash,
+                queryVariant,
+                typedQuery,
+                filters,
+            };
+            const signatureHash = stableRuntimeHash(body);
+            return { ...body, receiptId: `retrieval-request:${signatureHash}`, signatureHash };
+        });
+    });
+}
+function validateQueryVariants(channel, sourceHash, variants) {
+    if (!Array.isArray(variants) || variants.length === 0
+        || variants.filter(variant => variant.kind === 'original').length !== 1) {
+        throw new Error(`RETRIEVAL_${channel.toUpperCase()}_QUERY_VARIANTS_INVALID`);
+    }
+    const seen = new Set();
+    return variants.map(variant => {
+        const query = variant.query.normalize('NFKC').trim().slice(0, 2_000);
+        if (!query || !variant.producerId || !variant.producerVersion
+            || variant.sourceHash !== sourceHash
+            || variant.queryHash !== stableRuntimeHash({ query, sourceHash })
+            || seen.has(`${variant.kind}:${variant.queryHash}`)
+            || new Set(variant.sourceClaimIds).size !== variant.sourceClaimIds.length) {
+            throw new Error(`RETRIEVAL_${channel.toUpperCase()}_QUERY_VARIANT_INVALID`);
+        }
+        seen.add(`${variant.kind}:${variant.queryHash}`);
+        return { ...variant, query, sourceClaimIds: [...variant.sourceClaimIds].sort() };
+    });
+}
+function aggregateChannelAvailability(outputs) {
+    const result = {};
+    for (const channel of ['code', 'memory', 'knowledge']) {
+        const channelOutputs = outputs.filter(output => output.signature.channel === channel);
+        if (channelOutputs.length === 0)
+            continue;
+        const requiredOutputs = channelOutputs.filter(output => output.signature.queryVariant.kind === 'original');
+        result[channel] = requiredOutputs.some(output => output.result.availability === 'unavailable')
+            ? 'unavailable'
+            : channelOutputs.some(output => output.result.availability === 'available')
+                ? 'available'
+                : 'empty_valid';
+    }
+    return result;
+}
+function legOutcome(signature, result, failureStatus) {
+    const legId = `retrieval-leg:${stableRuntimeHash({
+        requestReceiptId: signature.signatureHash,
+        producerReceiptId: result.receipt.receiptId,
+    }).slice(0, 32)}`;
+    return {
+        schemaVersion: 'retrieval-leg-receipt.v1',
+        legId,
+        parentReceiptIds: [signature.receiptId, result.receipt.receiptId],
+        channel: signature.channel,
+        queryVariant: signature.queryVariant,
+        required: signature.queryVariant.kind === 'original',
+        status: failureStatus ?? executionStatus(result),
+        availability: result.availability,
+        candidateCount: result.candidates.length,
+        gapCount: result.gaps.length,
+        ...(result.availability === 'unavailable'
+            ? { reasonCode: result.gaps[0]?.reason ?? 'unavailable' }
+            : {}),
+        producerReceiptHash: result.receipt.receiptHash,
+    };
+}
+function executionStatus(result) {
+    const rawCandidateCount = producerCandidateCount(result);
+    if (result.availability === 'available') {
+        if (result.candidates.length === 0 && rawCandidateCount > 0)
+            return 'all_candidates_ineligible';
+        return result.candidates.length > 0 ? 'executed' : 'no_candidates';
+    }
+    if (result.availability === 'empty_valid') {
+        return rawCandidateCount > 0 ? 'all_candidates_ineligible' : 'no_candidates';
+    }
+    return 'unavailable';
+}
+function producerCandidateCount(result) {
+    const producerLegs = result.receipt.producerLegs ?? [];
+    return Math.max(result.candidates.length, ...producerLegs.map(leg => leg.candidateCount));
+}
+function retrievalExecutionStatus(input) {
+    if (input.rerankerFailed || input.legs.some(leg => leg.required && leg.status === 'failed'))
+        return 'failed';
+    if (input.legs.some(leg => leg.required && leg.status === 'unavailable'))
+        return 'unavailable';
+    if (input.rawCandidateCount > 0 && input.eligibleCount === 0)
+        return 'all_candidates_ineligible';
+    if (input.rawCandidateCount === 0)
+        return 'no_candidates';
+    return 'executed';
+}
+function providerFailureReason(error) {
+    const message = error instanceof Error ? error.message.toLowerCase() : '';
+    if (message.includes('timeout'))
+        return 'producer_timeout';
+    if (message.includes('invalid') || message.includes('mismatch'))
+        return 'producer_invalid';
+    return 'producer_exception';
+}
+function stopReason(cycle, remainingTokenBudget) {
+    if (cycle.sufficiency === 'sufficient')
+        return 'sufficient';
+    if (cycle.sufficiency === 'gap_unavailable')
+        return 'required_channel_unavailable';
+    if (cycle.sufficiency === 'abstain')
+        return 'abstain';
+    if (cycle.noGainCount >= 2)
+        return 'two_consecutive_no_gain_cycles';
+    if (cycle.cycle >= 3)
+        return 'maximum_cycles_reached';
+    if (remainingTokenBudget === 0)
+        return 'token_budget_exhausted';
+    return 'gap_actionable';
+}
+function hardFilter(candidates, requestedChannel, context, rejected, now) {
+    return candidates.filter(candidate => {
+        const vectorCandidate = candidate.contributingLegs.some(leg => /vector|embedding/iu.test(leg.leg));
+        const purpose = candidate.channel === 'code' ? 'code_retrieval'
+            : candidate.channel === 'memory' ? 'memory_retrieval' : 'knowledge_retrieval';
+        const expectedProfile = context.embeddingProfiles[purpose];
+        const allowedScopes = allowedScopeKeys(requestedChannel, context);
+        const minimumAuthority = requestedChannel === 'knowledge'
+            ? context.plan.knowledge.requirement === 'prohibited'
+                ? 0 : context.plan.knowledge.typedQuery.minimumAuthority ?? 0
+            : 0;
+        const scopeKey = `${candidate.eligibility.scope.kind}:${candidate.eligibility.scope.id}`;
+        const reason = candidate.channel !== requestedChannel ? 'producer_channel_mismatch'
+            : !allowedScopes.has(scopeKey) ? 'scope_mismatch'
+                : candidate.eligibility.permission !== 'allowed'
+                    ? candidate.eligibility.permission === 'denied' ? 'permission_denied' : 'permission_unknown'
+                    : candidate.eligibility.sourceReady !== true ? 'source_not_ready'
+                        : candidate.eligibility.expiresAt !== undefined && candidate.eligibility.expiresAt <= now ? 'expired'
+                            : requestedChannel === 'knowledge' && candidate.eligibility.authority === undefined && minimumAuthority > 0
+                                ? 'authority_missing'
+                                : requestedChannel === 'knowledge' && (candidate.eligibility.authority ?? 0) < minimumAuthority
+                                    ? 'authority_below_threshold'
+                                    : vectorCandidate && !expectedProfile ? 'profile_unbound'
+                                        : vectorCandidate && !candidate.eligibility.profileHash ? 'profile_missing'
+                                            : vectorCandidate && candidate.eligibility.profileHash !== expectedProfile ? 'profile_mismatch'
+                                                : !candidate.eligibility.sourceReady ? 'source_not_ready'
+                                                    : undefined;
+        if (reason)
+            rejected.push({ ref: candidate.stableRef, reason });
+        return !reason;
+    });
+}
+function scopeCandidateLegs(signature, candidate) {
+    const legs = candidate.contributingLegs.length > 0
+        ? candidate.contributingLegs
+        : [{
+                leg: candidate.channel,
+                rank: candidate.rank,
+                ...(candidate.score !== undefined ? { score: candidate.score } : {}),
+            }];
+    return {
+        ...candidate,
+        contributingLegs: legs.map(leg => ({
+            ...leg,
+            leg: `${signature.signatureHash}:${leg.leg}`,
+        })),
+    };
+}
+function unavailable(channel, context, reason, now, signature) {
+    const gap = {
+        kind: 'unavailable_channel', reason, evidenceRefs: [], resolver: channel, priority: 1,
+    };
+    const body = {
+        schemaVersion: 'evidence-receipt.v1',
+        receiptId: `unavailable:${channel}:${stableRuntimeHash({ context: context.contextHash, reason }).slice(0, 24)}`,
+        parentReceiptIds: signature ? [signature.receiptId] : [],
+        taskContextHash: context.contextHash,
+        channel,
+        availability: 'unavailable',
+        selectedRefs: [], rejectedRefs: [], gaps: [gap],
+        ...(signature ? { legId: signature.signatureHash } : {}),
+        factsHash: context.facts.factsHash,
+        planHash: context.plan.planHash,
+        activationSnapshotHash: context.activationSnapshotHash,
+        createdAt: now,
+    };
+    return { availability: 'unavailable', candidates: [], gaps: [gap], receipt: { ...body, receiptHash: stableRuntimeHash(body) } };
+}
+function providerReceipt(input) {
+    const executionId = `provider-execution:${stableRuntimeHash(input.executionKey).slice(0, 32)}`;
+    const body = {
+        schemaVersion: 'provider-execution-receipt.v1',
+        receiptId: `provider-execution-receipt:${stableRuntimeHash(executionId).slice(0, 32)}`,
+        executionId,
+        requestHash: input.requestHash,
+        providerId: input.providerId,
+        providerVersion: input.providerVersion,
+        capability: 'reranking',
+        status: input.status,
+        proposalCount: input.proposalCount,
+        acceptedCount: input.acceptedCount,
+        rejectedCount: input.rejectedCount,
+        reasonCodes: [...new Set(input.reasonCodes)].sort(),
+        latencyMs: Math.max(0, Math.round(input.latencyMs)),
+        createdAt: input.createdAt,
+    };
+    return { ...body, receiptHash: stableRuntimeHash(body) };
+}
+function providerLogData(receipt) {
+    return {
+        executionId: receipt.executionId,
+        requestHash: receipt.requestHash,
+        providerIdHash: stableRuntimeHash(receipt.providerId),
+        providerVersionHash: stableRuntimeHash(receipt.providerVersion),
+        providerReceiptId: receipt.receiptId,
+        providerReceiptHash: receipt.receiptHash,
+        capability: receipt.capability,
+        status: receipt.status,
+        proposalCount: receipt.proposalCount,
+        acceptedCount: receipt.acceptedCount,
+        rejectedCount: receipt.rejectedCount,
+        reasonCodes: receipt.reasonCodes,
+        latencyMs: receipt.latencyMs,
+    };
+}
+function validateProducerResult(signature, context, result) {
+    const channel = signature.channel;
+    const { receiptHash, ...receiptBody } = result.receipt;
+    if (stableRuntimeHash(receiptBody) !== receiptHash
+        || result.receipt.schemaVersion !== 'evidence-receipt.v1'
+        || result.receipt.legId !== signature.signatureHash
+        || !result.receipt.parentReceiptIds.includes(signature.receiptId)
+        || result.receipt.taskContextHash !== context.contextHash
+        || result.receipt.channel !== channel
+        || result.receipt.availability !== result.availability
+        || result.receipt.factsHash !== context.facts.factsHash
+        || result.receipt.planHash !== context.plan.planHash
+        || result.receipt.activationSnapshotHash !== context.activationSnapshotHash
+        || stableRuntimeHash(result.receipt.gaps) !== stableRuntimeHash(result.gaps)) {
+        throw new Error('PRODUCER_RECEIPT_INVALID');
+    }
+    const producerLegs = result.receipt.producerLegs ?? [];
+    const requiredLexical = producerLegs.find(leg => leg.kind === 'lexical' && leg.required);
+    const requiredVector = producerLegs.find(leg => leg.kind === 'vector' && leg.required);
+    const successfulLegStatuses = new Set(['ready', 'empty_valid']);
+    if (producerLegs.some(leg => leg.schemaVersion !== 'evidence-producer-leg-receipt.v1'
+        || !leg.parentReceiptIds.includes(signature.receiptId))
+        || !requiredLexical
+        || (signature.filters.embeddingProfileHash && !requiredVector)
+        || (result.availability !== 'unavailable'
+            && (!successfulLegStatuses.has(requiredLexical.status)
+                || (requiredVector && !successfulLegStatuses.has(requiredVector.status))))) {
+        throw new Error('PRODUCER_REQUIRED_LEG_RECEIPT_INVALID');
+    }
+    if ((result.availability === 'unavailable' || result.availability === 'empty_valid')
+        && result.candidates.length > 0)
+        throw new Error('PRODUCER_AVAILABILITY_CONFLICT');
+    if (result.availability === 'unavailable'
+        && !result.gaps.some(gap => gap.kind === 'unavailable_channel')) {
+        throw new Error('PRODUCER_UNAVAILABLE_GAP_MISSING');
+    }
+    for (const candidate of result.candidates) {
+        if (!candidate.stableRef || candidate.channel !== channel
+            || !Number.isSafeInteger(candidate.rank) || candidate.rank < 1
+            || !candidate.eligibility
+            || !candidate.eligibility.scope?.id
+            || !['project', 'session', 'skill'].includes(candidate.eligibility.scope.kind)
+            || !['allowed', 'denied', 'unknown'].includes(candidate.eligibility.permission)
+            || typeof candidate.eligibility.sourceReady !== 'boolean'
+            || (candidate.eligibility.authority !== undefined
+                && (!Number.isFinite(candidate.eligibility.authority)
+                    || candidate.eligibility.authority < 0 || candidate.eligibility.authority > 1))) {
+            throw new Error('PRODUCER_CANDIDATE_INVALID');
+        }
+        stableRuntimeHash(candidate);
+    }
+    return result;
+}
+function allowedScopeKeys(channel, context) {
+    const kinds = channel === 'memory'
+        ? new Set(context.plan.memory.requirement === 'prohibited' ? [] : context.plan.memory.typedQuery.scopes)
+        : new Set(['project']);
+    return new Set([context.scopeBindings.project, context.scopeBindings.session, context.scopeBindings.skill]
+        .filter((scope) => Boolean(scope) && kinds.has(scope.kind))
+        .map(scope => `${scope.kind}:${scope.id}`));
+}
+function dedupeStrings(values) {
+    return [...new Set(values)];
+}
+function dedupeRejected(values) {
+    return [...new Map(values.map(value => [`${value.ref}\0${value.reason}`, value])).values()];
+}
+function rejectionReasonCounts(values) {
+    const counts = {};
+    for (const value of values)
+        counts[value.reason] = (counts[value.reason] ?? 0) + 1;
+    return Object.fromEntries(Object.entries(counts).sort(([left], [right]) => left.localeCompare(right)));
+}
+function mergeContributingLegs(left, right) {
+    const result = {};
+    for (const source of [left ?? {}, right ?? {}])
+        for (const [leg, values] of Object.entries(source)) {
+            result[leg] = [...new Map([...(result[leg] ?? []), ...values]
+                    .map(value => [`${value.ref}\0${value.rank}`, value])).values()];
+        }
+    return result;
+}
+function mergeSelectedRefsByChannel(left, right) {
+    return Object.fromEntries(['code', 'memory', 'knowledge'].map(channel => [
+        channel,
+        dedupeStrings([...(left?.[channel] ?? []), ...(right?.[channel] ?? [])]),
+    ]));
+}
+function mergeSelectedEvidence(left, right) {
+    return [...new Map([...(left ?? []), ...(right ?? [])]
+            .map(candidate => [candidate.stableRef, candidate])).values()];
+}
+function mergeLegOutcomes(left, right) {
+    return [...new Map([...(left ?? []), ...right].map(outcome => [outcome.legId, outcome])).values()];
+}
+function evidenceStageReceipt(candidate, stage, parentReceiptIds, createdAt, reasonCode, rank) {
+    const parents = dedupeStrings(parentReceiptIds).sort();
+    const body = {
+        schemaVersion: 'evidence-stage-receipt.v1',
+        receiptId: `evidence-stage:${stableRuntimeHash({
+            stableRef: candidate.stableRef,
+            stage,
+            parents,
+            ...(reasonCode ? { reasonCode } : {}),
+            ...(rank !== undefined ? { rank } : {}),
+            createdAt,
+        }).slice(0, 32)}`,
+        parentReceiptIds: parents,
+        stableRef: candidate.stableRef,
+        channel: candidate.channel,
+        stage,
+        ...(rank !== undefined ? { rank } : {}),
+        ...(reasonCode ? { reasonCode } : {}),
+        createdAt,
+    };
+    return { ...body, receiptHash: stableRuntimeHash(body) };
+}
+function evidenceStageReceiptFrom(parent, stage, createdAt, reasonCode) {
+    return evidenceStageReceipt({
+        stableRef: parent.stableRef,
+        channel: parent.channel,
+    }, stage, [parent.receiptId], createdAt, reasonCode);
+}
+function evidenceReceiptIdsByRef(receipts) {
+    const result = new Map();
+    for (const receipt of receipts) {
+        result.set(receipt.stableRef, [
+            ...(result.get(receipt.stableRef) ?? []),
+            receipt.receiptId,
+        ]);
+    }
+    return result;
+}
+function dedupeEvidenceStageReceipts(receipts) {
+    return [...new Map(receipts.map(receipt => [receipt.receiptId, receipt])).values()];
+}
+function requiresStrongCodeEvidence(context) {
+    return context.actionAuthority.mutation === 'authorized'
+        || context.actionAuthority.mutation === 'conditional';
+}
+function executableChannelCount(context) {
+    return [context.plan.code, context.plan.memory, context.plan.knowledge]
+        .filter(plan => plan.requirement !== 'prohibited').length;
+}
+function dedupeGaps(gaps) {
+    return [...new Map(gaps.map(gap => [stableRuntimeHash(gap), gap])).values()]
+        .sort((left, right) => left.priority - right.priority || left.kind.localeCompare(right.kind));
+}
+//# sourceMappingURL=retrieval-coordinator.js.map