@untangle-code/search 0.0.0-stage → 0.1.0

package/dist/engine.js

@@ -0,0 +1,1498 @@
+import { DEFAULT_SEARCH_CONFIG } from "@untangle-code/config";
+import { buildSearchQueryFingerprint, canonicalJson, compareCodepoints, INDEX_CONTEXT_INCOMPLETE_WARNING_CODE, isUntangleError, normalizeSearchQuery, sha256Hex, sortByCodepoints, UntangleError, uniqueSortedByCodepoints, } from "@untangle-code/domain";
+import { Bm25Ranker } from "./bm25.js";
+import { dedupeCandidates } from "./dedupe.js";
+import { assignDuplicatePenalties } from "./diversify.js";
+import { SEARCH_GRAPH_RELATION_LIMIT, boundSearchGraphDetail, createSearchGraphRelations, unavailableSearchGraphRelations, } from "./enrichment.js";
+import { buildPayloadFilter } from "./filter.js";
+import { DEFAULT_BRANCH_WEIGHTS, fuseRankings } from "./fusion.js";
+import { assertValidGlobPatterns, isPathSelected } from "./glob.js";
+import { grepIndexedChunks } from "./grep.js";
+import { SearchSkipLedger } from "./ledger.js";
+import { candidateFromPoint, lexicalDocumentText, readRawString } from "./payload.js";
+import { relevancePrerequisiteFailure } from "./relevance-prerequisites.js";
+import { NO_SUFFICIENT_MATCH_WARNING_CODE, RELEVANCE_POLICY_NOT_EVALUATED_WARNING_CODE, decideResultRelevance, resolveRelevancePolicyBinding, selectFixedRelevanceEvidencePool, } from "./relevance.js";
+import { assertCompletedRetrieval, branchesOfMode, retrieveIndependentBranches, rethrowCancellation, } from "./retrieval.js";
+import { MAX_BOOST_SHARE, assembleScoreBreakdown } from "./scoring.js";
+import { assignRanks, sortHits } from "./sort.js";
+import { matchSymbolName } from "./symbol-match.js";
+import { isLikelyGermanQuestion } from "./tokenize.js";
+/** Halbwertszeit des Recency-Boosts, wenn keine gesetzt ist. */
+export const DEFAULT_RECENCY_HALF_LIFE_DAYS = 30;
+/** Harte Grenze fuer freie Providerwarnungen und Batch-Diagnose-IDs. */
+export const SEARCH_GRAPH_DIAGNOSTIC_LIMIT = 32;
+/** Providerwarnungen sind eine eigene Ausgabeachse und deshalb separat gedeckelt. */
+export const SEARCH_GRAPH_PROVIDER_WARNING_LIMIT = 16;
+function normalizeGraphProviderWarning(warning) {
+    const source = warning.details;
+    const details = {};
+    if (source !== undefined && source !== null && typeof source === "object") {
+        if (typeof source["workspaceId"] === "string") {
+            details["workspaceId"] = boundSearchGraphDetail(source["workspaceId"]);
+        }
+        if (typeof source["generationId"] === "string") {
+            details["generationId"] = boundSearchGraphDetail(source["generationId"]);
+        }
+        const rawIssues = source["issues"];
+        if (Array.isArray(rawIssues)) {
+            const issues = rawIssues.map(String).map(boundSearchGraphDetail).sort(compareCodepoints);
+            details["issues"] = issues.slice(0, SEARCH_GRAPH_PROVIDER_WARNING_LIMIT);
+            const providerOmitted = source["omittedIssueCount"];
+            const providerOmittedCount = typeof providerOmitted === "number" &&
+                Number.isSafeInteger(providerOmitted) &&
+                providerOmitted >= 0
+                ? providerOmitted
+                : 0;
+            details["omittedIssueCount"] =
+                providerOmittedCount + Math.max(0, issues.length - SEARCH_GRAPH_PROVIDER_WARNING_LIMIT);
+        }
+        const retainedKeys = new Set(["workspaceId", "generationId", "issues", "omittedIssueCount"]);
+        const omittedDetailFieldCount = Object.keys(source).filter((key) => !retainedKeys.has(key)).length;
+        if (omittedDetailFieldCount > 0) {
+            details["omittedDetailFieldCount"] = omittedDetailFieldCount;
+        }
+    }
+    return {
+        code: boundSearchGraphDetail(String(warning.code)),
+        message: boundSearchGraphDetail(String(warning.message)),
+        ...(Object.keys(details).length === 0 ? {} : { details }),
+    };
+}
+function boundedDiagnosticIds(values) {
+    const sorted = sortByCodepoints([...new Set(values)]);
+    return {
+        ids: sorted.slice(0, SEARCH_GRAPH_DIAGNOSTIC_LIMIT).map(boundSearchGraphDetail),
+        omittedCount: Math.max(0, sorted.length - SEARCH_GRAPH_DIAGNOSTIC_LIMIT),
+    };
+}
+export const DEFAULT_SEARCH_BRANCH_TIMEOUT_MS = 10_000;
+/**
+ * Gibt dem PRAEZISIONSzweig bei einer zeichengleichen Symbolanfrage genug
+ * Basisgewicht, dass ein exakter Treffer selbst unter den erlaubten
+ * Boost-Grenzfaellen vor einem nicht-exakten Treffer bleibt.
+ *
+ * Bei MAX_BOOST_SHARE=0.5 kann ein nicht-exakter Basisscore hoechstens auf
+ * 1.5x steigen und ein exakter durch Strafen hoechstens auf 0.5x fallen. Das
+ * benoetigte Basisverhaeltnis ist daher (1+s)/(1-s)=3. Der kleine vorhandene
+ * Symbolanteil oberhalb dieser Grenze macht die Ungleichung strikt. Der
+ * Boost-Deckel selbst bleibt vollkommen unveraendert.
+ */
+export function exactSymbolIntentBranchWeights(weights, active) {
+    if (!active.symbol || weights.symbol <= 0) {
+        return { ...weights };
+    }
+    const nonSymbolWeight = (active.dense ? Math.max(0, weights.dense) : 0) +
+        (active.lexical ? Math.max(0, weights.lexical) : 0);
+    const dominanceRatio = (1 + MAX_BOOST_SHARE) / (1 - MAX_BOOST_SHARE);
+    return {
+        ...weights,
+        symbol: Math.max(weights.symbol, nonSymbolWeight * dominanceRatio + weights.symbol),
+    };
+}
+/** Zahl dichter Spitzenplaetze, die einen lexikalischen Spitzenkandidaten bestaetigen. */
+export const GERMAN_LEXICAL_CORROBORATION_DEPTH = 10;
+/**
+ * Nur eine als deutsch erkannte Frage mit einem lexikalischen Spitzenreiter,
+ * der NICHT unter den zehn dicht besten Kandidaten vorkommt, verliert im
+ * Hybridmodus den lokalen BM25-Rang. Stimmen beide unabhaengigen Zweige
+ * ueberein, bleibt das nuetzliche lexikalische Signal erhalten.
+ */
+export function shouldOmitUncorroboratedGermanLexicalBranch(queryText, denseRankedIds, lexicalRankedIds) {
+    if (!isLikelyGermanQuestion(queryText)) {
+        return false;
+    }
+    const lexicalTop = lexicalRankedIds[0];
+    if (lexicalTop === undefined) {
+        return true;
+    }
+    return !denseRankedIds.slice(0, GERMAN_LEXICAL_CORROBORATION_DEPTH).includes(lexicalTop);
+}
+/** Normalisiert die Zusatzfelder dieses Pakets (Gegenstueck zu `SearchQueryV1`). */
+export function normalizeExtensions(request) {
+    const pathExcludes = uniqueSortedByCodepoints((request.pathExclude ?? []).map((value) => value.trim()).filter((value) => value !== ""));
+    return {
+        mode: request.mode ?? "hybrid",
+        abstention: request.abstention ?? "strict",
+        pathExcludes,
+        includeContent: request.includeContent ?? false,
+        complexityBias: request.complexityBias ?? "none",
+        sort: request.sort ?? "relevance",
+    };
+}
+/**
+ * Die Zusatzangaben, die den Fingerabdruck der Anfrage veraendern MUESSEN.
+ *
+ * Der Fingerabdruck beantwortet „ist das dieselbe Frage?". `mode`,
+ * `pathExcludes`, `complexityBias` und `sort` aendern die Treffermenge bzw.
+ * die Rangfolge — zwei Anfragen, die sich nur darin unterscheiden, sind NICHT
+ * dieselbe Frage. `includeContent` bleibt draussen: es aendert nur die
+ * Darstellung, genau wie `limit` und `candidateLimit` (siehe
+ * `buildSearchQueryFingerprint`).
+ *
+ * Nur ABWEICHUNGEN vom Standard gehen ein. Eine Anfrage ohne
+ * Paket-Erweiterungen behaelt damit exakt den Fingerabdruck, den sie ohne
+ * dieses Feld haette — Findability-Datensaetze aelterer Laeufe bleiben
+ * vergleichbar.
+ */
+export function fingerprintRankingOptions(extensions) {
+    const options = {};
+    if (extensions.mode !== "hybrid") {
+        options["mode"] = extensions.mode;
+    }
+    if (extensions.pathExcludes.length > 0) {
+        options["pathExcludes"] = extensions.pathExcludes;
+    }
+    if (extensions.complexityBias !== "none") {
+        options["complexityBias"] = extensions.complexityBias;
+    }
+    if (extensions.sort !== "relevance") {
+        options["sort"] = extensions.sort;
+    }
+    // NUR bei Abweichung. `strict` traegt nichts bei, damit jeder bereits
+    // persistierte `queryFingerprint` byte-identisch bleibt — sonst waeren alle
+    // Findability-Datensaetze und Journey-Kohorten auf einen Schlag entwertet.
+    if (extensions.abstention !== "strict") {
+        options["abstention"] = extensions.abstention;
+    }
+    return Object.keys(options).length === 0 ? undefined : options;
+}
+/**
+ * Ergaenzt die Findability-Filter aus der Paketanfrage in die normalisierten
+ * Domain-Filter. `normalizeSearchQuery` kennt sie nicht, weil `SearchRequestV1`
+ * (spec.md §13.1) sie nicht kennt — `SearchFiltersV1` hat das Feld aber
+ * bereits, also wird es hier gefuellt statt neben der Query gefuehrt.
+ */
+function withFindabilityFilter(query, request) {
+    const { findabilityMinScore, findabilityMaxScore } = request;
+    if (findabilityMinScore === undefined && findabilityMaxScore === undefined) {
+        return query;
+    }
+    if (findabilityMinScore !== undefined &&
+        findabilityMaxScore !== undefined &&
+        findabilityMinScore > findabilityMaxScore) {
+        throw new Error(`search query filter "findability" has min > max (${findabilityMinScore} > ${findabilityMaxScore})`);
+    }
+    const filters = {
+        ...query.filters,
+        findability: {
+            ...(findabilityMinScore === undefined ? {} : { minScore: findabilityMinScore }),
+            ...(findabilityMaxScore === undefined ? {} : { maxScore: findabilityMaxScore }),
+        },
+    };
+    return { ...query, filters };
+}
+/**
+ * WP-188 (E4): `searchConfig.diversifyByDefault` und `searchConfig.minScoreDefault`
+ * hatten KEINEN Leser.
+ *
+ * Beide standen in der Konfiguration, waren dokumentiert, wurden validiert —
+ * und veraenderten nichts. Eine Einstellung, die nichts tut, ist schlimmer als
+ * eine fehlende: sie behauptet eine Wirkung. Wer `minScoreDefault = 0.5`
+ * setzte und weiterhin Treffer mit 0.2 bekam, hatte keinen Grund, den Fehler
+ * beim Werkzeug zu suchen.
+ *
+ * Die Vorgaben greifen nur, wo die ANFRAGE nichts sagt — eine ausdrueckliche
+ * Angabe des Aufrufers gewinnt immer. Sie werden VOR dem Fingerabdruck
+ * angewandt, damit „gleiche Frage" auch dann gleich heisst, wenn ein Teil der
+ * Antwort aus der Konfiguration kommt.
+ */
+function applyConfigDefaults(query, request, config) {
+    const diversify = request.diversify ?? config.diversifyByDefault;
+    const useConfigMinScore = request.minScore === undefined &&
+        config.minScoreDefault !== undefined &&
+        Number.isFinite(config.minScoreDefault);
+    return {
+        query: {
+            ...query,
+            diversify,
+            ...(useConfigMinScore ? { minScore: config.minScoreDefault } : {}),
+        },
+        minScoreFromConfig: useConfigMinScore,
+    };
+}
+/**
+ * Die Referenzimplementierung des {@link SearchPort}.
+ *
+ * Sie ist speicher-agnostisch: alles laeuft ueber den `VectorStore`-Port, also
+ * gegen Qdrant genauso wie gegen den In-Memory-Speicher des testkits.
+ */
+export class HybridSearchEngine {
+    deps;
+    config;
+    branchWeights;
+    branchTimeoutMs;
+    relevancePolicies;
+    constructor(deps) {
+        this.deps = deps;
+        const seenProfileIds = new Set();
+        for (const target of deps.targets) {
+            if (target.embeddingProfileId !== target.embedder.profileId) {
+                throw new Error(`search target embeddingProfileId "${target.embeddingProfileId}" does not match its embedder.profileId "${target.embedder.profileId}"; collection/profile grouping and calibrated policies would be misattributed`);
+            }
+            if (seenProfileIds.has(target.embeddingProfileId)) {
+                throw new Error(`search target embeddingProfileId "${target.embeddingProfileId}" is configured more than once; one result group per embedding profile is required`);
+            }
+            seenProfileIds.add(target.embeddingProfileId);
+        }
+        this.config = deps.searchConfig ?? DEFAULT_SEARCH_CONFIG;
+        this.branchWeights = deps.branchWeights ?? { ...DEFAULT_BRANCH_WEIGHTS };
+        this.branchTimeoutMs = deps.branchTimeoutMs ?? DEFAULT_SEARCH_BRANCH_TIMEOUT_MS;
+        if (!Number.isSafeInteger(this.branchTimeoutMs) ||
+            this.branchTimeoutMs <= 0 ||
+            this.branchTimeoutMs > 2_147_483_647) {
+            throw new Error("branchTimeoutMs must be an integer between 1 and 2147483647");
+        }
+        // Die projektweite Config ist selbst eine vollwertige Verdrahtungsquelle.
+        // Das explizite Dependency-Feld bleibt fuer Library-Aufrufer und Tests,
+        // gewinnt bei gleichzeitiger Angabe aber eindeutig. Sonst waere eine
+        // geladene, validierte SearchConfig erneut ein wirkungsloser Wert.
+        const configuredRelevancePolicies = deps.relevancePolicies ?? this.config.relevancePolicies;
+        this.relevancePolicies = new Map(Object.entries(configuredRelevancePolicies ?? {}).map(([embeddingProfileId, configured]) => {
+            if (embeddingProfileId.trim() === "") {
+                throw new Error("relevancePolicies keys must be non-empty embedding profile ids");
+            }
+            return [embeddingProfileId, resolveRelevancePolicyBinding(configured)];
+        }));
+    }
+    async search(request, options) {
+        options?.signal?.throwIfAborted();
+        const extensions = normalizeExtensions(request);
+        const defaulted = applyConfigDefaults(withFindabilityFilter(normalizeSearchQuery(request, this.deps.defaults), request), request, this.config);
+        const query = defaulted.query;
+        // Der Ursprung reist als Parameter mit, NICHT als Feld der Instanz: zwei
+        // gleichzeitige `search()`-Aufrufe auf derselben Maschine wuerden sich
+        // sonst gegenseitig die Begruendung im Ledger umschreiben.
+        const minScoreOrigin = defaulted.minScoreFromConfig
+            ? "from searchConfig.minScoreDefault"
+            : "requested";
+        // Fehlerhafte Muster sind ein Eingabefehler des Nutzers und werden HIER
+        // abgelehnt. Faellt der Fehler erst beim Abgleich je Kandidat an, faengt
+        // ihn das Ziel-catch auf und meldet einen Speicherausfall — eine falsche
+        // Diagnose fuer ein falsches Zeichen im Suchmuster.
+        assertValidGlobPatterns(query.filters.pathGlobs, "pathGlob");
+        assertValidGlobPatterns(extensions.pathExcludes, "pathExclude");
+        const ledger = new SearchSkipLedger();
+        const warnings = [];
+        // Die Obergrenze aus der Konfiguration ist eine Grenze, kein Vorschlag:
+        // ohne sie zieht eine Anfrage mit candidateLimit=100000 drei Rundlaeufe
+        // ueber 100000 Punkte plus einen BM25-Aufbau darueber.
+        //
+        // WARUM AUCH `limit` GEDECKELT WIRD: `SearchQueryV1` verlangt
+        // `candidateLimit >= limit`, und `normalizeSearchQuery` weist alles andere
+        // ab. Wer die Obergrenze nur auf `candidateLimit` anwendet und den Wert
+        // anschliessend mit `Math.max(max, limit)` wieder anhebt, hat die Grenze
+        // damit fuer JEDE Anfrage mit grossem `limit` ausgeschaltet — die drei
+        // Speicherrundlaeufe ueber 100000 Punkte laufen dann wie zuvor. Die
+        // Obergrenze ist eine Aussage ueber die ARBEIT, nicht ueber ein einzelnes
+        // Feld: mehr als `maxCandidateLimit` Kandidaten werden nicht geholt, also
+        // koennen auch nicht mehr als `maxCandidateLimit` Treffer entstehen. Beide
+        // Deckelungen stehen einzeln und benannt im Ergebnis (E4).
+        const maxCandidateLimit = this.config.maxCandidateLimit;
+        const candidateCapActive = Number.isInteger(maxCandidateLimit) && maxCandidateLimit > 0;
+        let candidateLimit = query.candidateLimit;
+        let limit = query.limit;
+        if (candidateCapActive && candidateLimit > maxCandidateLimit) {
+            candidateLimit = maxCandidateLimit;
+            warnings.push({
+                code: "CANDIDATE_LIMIT_CLAMPED",
+                message: `candidateLimit ${query.candidateLimit} exceeds the configured maximum of ${maxCandidateLimit}; the search ran with ${candidateLimit} candidates per branch instead`,
+                details: {
+                    requested: query.candidateLimit,
+                    effective: candidateLimit,
+                    maxCandidateLimit,
+                },
+            });
+        }
+        if (limit > candidateLimit) {
+            warnings.push({
+                code: "RESULT_LIMIT_CLAMPED",
+                message: `limit ${limit} exceeds the candidate pool of ${candidateLimit} (configured maximum ${maxCandidateLimit}); the search returned at most ${candidateLimit} hits per profile group instead`,
+                details: {
+                    requested: limit,
+                    effective: candidateLimit,
+                    candidateLimit,
+                    maxCandidateLimit,
+                },
+            });
+            limit = candidateLimit;
+        }
+        const effectiveQuery = {
+            ...query,
+            includeContent: extensions.includeContent,
+            candidateLimit,
+            limit,
+        };
+        // Die VOLLSTAENDIGE normalisierte Anfrage geht hinein, nicht eine von Hand
+        // gepflegte Auswahl daraus: `buildSearchQueryFingerprint` streicht selbst,
+        // was reine Darstellung ist (siehe SEARCH_FINGERPRINT_IGNORED_FIELDS).
+        // Wuerde hier eine Auswahl stehen, fiele jedes spaeter ergaenzte
+        // ergebnisveraendernde Feld wieder lautlos heraus — genau so verloren
+        // `workspaceId`, `minScore` und `diversify` ihren Platz im Fingerabdruck.
+        const rankingOptions = fingerprintRankingOptions(extensions);
+        const fingerprint = buildSearchQueryFingerprint({
+            ...effectiveQuery,
+            ...(rankingOptions === undefined ? {} : { rankingOptions }),
+        });
+        const rankingContextFingerprint = this.rankingContextFingerprint(effectiveQuery, extensions);
+        // Ein nicht verdrahteter Port bleibt derselbe ehrliche UNAVAILABLE-Fall
+        // wie bisher. Ist einer vorhanden, wird er erst NACH Ranking, Dedupe und
+        // Limit gerufen (unterhalb der Zielschleife).
+        if (effectiveQuery.includeGraphContext && this.deps.graphEnrichment === undefined) {
+            warnings.push({
+                code: "GRAPH_CONTEXT_UNAVAILABLE",
+                message: "the request asked for structural graph context (includeContext), but no graph enrichment provider is wired; the hits carry NO graph context",
+            });
+        }
+        if (effectiveQuery.includeLinked && this.deps.graphEnrichment === undefined) {
+            warnings.push({
+                code: "LINKED_ARTIFACTS_UNAVAILABLE",
+                message: "the request asked for linked symbols (includeLinked), but no graph enrichment provider is wired; the hits carry NO linked symbols",
+            });
+        }
+        if (effectiveQuery.filters.findability !== undefined && this.deps.findability === undefined) {
+            warnings.push({
+                code: "FINDABILITY_FILTER_UNAVAILABLE",
+                message: "the request asked for a findability filter, but no findability lookup is wired into the engine — the filter was NOT applied",
+                details: { filter: effectiveQuery.filters.findability },
+            });
+        }
+        if (branchesOfMode(extensions.mode).lexical && this.deps.sparseVectorizer === undefined) {
+            warnings.push({
+                code: "SPARSE_RECALL_UNAVAILABLE",
+                message: "no sparse vectorizer is wired into the engine; the requested lexical retrieval branch is unavailable",
+            });
+        }
+        const groups = [];
+        const failedTargets = [];
+        const refIdsByRepo = new Map();
+        for (const target of this.deps.targets) {
+            options?.signal?.throwIfAborted();
+            try {
+                const outcome = await this.searchTarget(target, effectiveQuery, extensions, ledger, minScoreOrigin, options);
+                groups.push(outcome.group);
+                warnings.push(...(outcome.branchWarnings ?? []));
+                if (outcome.relevanceWarning !== undefined) {
+                    warnings.push(outcome.relevanceWarning);
+                }
+                if (outcome.indexContextWarning !== undefined) {
+                    warnings.push(outcome.indexContextWarning);
+                }
+                for (const hit of outcome.group.hits) {
+                    const set = refIdsByRepo.get(hit.repoId) ?? new Set();
+                    set.add(hit.refId);
+                    refIdsByRepo.set(hit.repoId, set);
+                }
+            }
+            catch (error) {
+                rethrowCancellation(error, options);
+                // E4: ein ausgefallenes Ziel wird gemeldet, nicht verschluckt. Die
+                // uebrigen Profile werden weiter durchsucht (spec.md §25.2: eine
+                // Lesende Operation degradiert sichtbar, statt ganz zu scheitern).
+                const message = error instanceof Error ? error.message : String(error);
+                const code = isUntangleError(error) ? error.code : "PROFILE_UNAVAILABLE";
+                failedTargets.push({ profileId: target.embeddingProfileId, error });
+                warnings.push({
+                    code,
+                    message: `profile "${target.embeddingProfileId}" could not be searched: ${message}`,
+                    details: { collection: target.collection, repoIds: target.repoIds },
+                });
+                ledger.add({
+                    subjectKind: "search_candidate",
+                    subjectId: target.embeddingProfileId,
+                    reason: "provider_unavailable",
+                    detail: `collection "${target.collection}" did not answer: ${message}`,
+                    recoverable: true,
+                });
+                this.deps.logger?.log({
+                    timestamp: this.deps.clock?.nowIso() ?? "",
+                    level: "warn",
+                    component: "search",
+                    event: "profile_search_failed",
+                    context: { profileId: target.embeddingProfileId, message },
+                });
+            }
+        }
+        if (failedTargets.length > 0 &&
+            !groups.some((group) => group.notSearchedReason === undefined)) {
+            const first = failedTargets[0];
+            throw new UntangleError(isUntangleError(first.error) ? first.error.code : "QDRANT_UNAVAILABLE", `search failed: no requested profile completed a retrieval branch; ${failedTargets
+                .map(({ profileId, error }) => `profile "${profileId}": ${error instanceof Error ? error.message : String(error)}`)
+                .join("; ")}`, {
+                operation: "search",
+                retryable: failedTargets.some(({ error }) => !isUntangleError(error) || error.retryable),
+                context: { failedProfileIds: failedTargets.map(({ profileId }) => profileId) },
+                cause: first.error,
+            });
+        }
+        // Pipeline-Schritt 11: Nur die BEREITS final begrenzten und gerankten
+        // Treffer verlassen den Abrufkern in Richtung Graphadapter. Weder ein
+        // Graphsignal noch ein Ladefehler kann dadurch Ranking, Score, Dedupe,
+        // Fingerabdruck oder Trefferzahl veraendern.
+        //
+        // Diese Bedingung fragt, ob es ueberhaupt einen Treffer gibt, an den man
+        // Relationen haengen kann. Sie ist AUSDRUECKLICH KEINE Enthaltungspruefung:
+        // unter `evidence` behaelt eine von der Policy abgelehnte Gruppe ihre
+        // Treffer und wird folgerichtig angereichert. Anreicherung zu ueberspringen,
+        // weil die Policy ablehnte, waere eine zweite, verdeckte Bedeutung an
+        // derselben Stelle — genau die Verwechslung, die diese Welle beseitigt.
+        const hasHitsToEnrich = groups.some((group) => group.hits.length > 0);
+        if (this.deps.graphEnrichment !== undefined &&
+            (effectiveQuery.includeGraphContext || effectiveQuery.includeLinked) &&
+            hasHitsToEnrich) {
+            await this.enrichFinalHits(groups, effectiveQuery, warnings, options);
+        }
+        for (const [repoId, refIds] of refIdsByRepo) {
+            if (refIds.size > 1) {
+                warnings.push({
+                    code: "MULTIPLE_REFS",
+                    message: `repository "${repoId}" contributed hits from ${refIds.size} refs; results from different refs describe different states of the same code`,
+                    details: { repoId, refIds: sortByCodepoints([...refIds]) },
+                });
+            }
+        }
+        const incompleteHits = groups.flatMap((group) => group.hits.filter((hit) => hit.incompletePayloadFields !== undefined));
+        if (incompleteHits.length > 0) {
+            warnings.push({
+                code: "INCOMPLETE_PAYLOAD",
+                message: `${incompleteHits.length} hit(s) carry payload fields that were missing in the index and filled with documented substitutes; see each hit's incompletePayloadFields`,
+                details: {
+                    chunkIds: sortByCodepoints(incompleteHits.map((hit) => hit.chunkId)),
+                },
+            });
+        }
+        const profileSeparation = groups.length > 1;
+        if (profileSeparation) {
+            warnings.push({
+                code: "PROFILE_SEPARATION",
+                message: "results are grouped per embedding profile; scores are comparable only WITHIN a group (spec.md §13.4)",
+                details: { profileIds: groups.map((group) => group.embeddingProfileId) },
+            });
+        }
+        return {
+            schemaVersion: 1,
+            queryFingerprint: fingerprint,
+            rankingContextFingerprint,
+            query: effectiveQuery,
+            groups,
+            profileSeparation,
+            totalHits: groups.reduce((sum, group) => sum + group.hits.length, 0),
+            skipped: ledger.toArray(),
+            warnings,
+        };
+    }
+    rankingContextFingerprint(query, extensions) {
+        const targets = this.deps.targets
+            .map((target) => ({
+            embeddingProfileId: target.embeddingProfileId,
+            collection: target.collection,
+            repoIds: uniqueSortedByCodepoints(target.repoIds),
+        }))
+            .sort((left, right) => compareCodepoints(canonicalJson(left), canonicalJson(right)));
+        const relevancePolicies = [...this.relevancePolicies.entries()]
+            .sort(([left], [right]) => compareCodepoints(left, right))
+            .map(([embeddingProfileId, binding]) => ({ embeddingProfileId, ...binding }));
+        const repoPriorities = Object.entries(this.deps.repoPriorities ?? {}).sort(([left], [right]) => compareCodepoints(left, right));
+        return sha256Hex(canonicalJson({
+            schemaVersion: 1,
+            rankerVersion: query.rankerVersion,
+            mode: extensions.mode,
+            // Mode-selected recall and independent branch failure handling must
+            // never be cohort-compatible with the previous rank-only strategy.
+            retrievalStrategy: "independent-branches-v1",
+            ...(extensions.mode === "hybrid" ? { branchTimeoutMs: this.branchTimeoutMs } : {}),
+            // Ausdruecklicher bedingter Spread, NICHT `abstention: x ?? undefined`:
+            // der Hash darf nicht davon abhaengen, ob canonicalJson undefined
+            // wegwirft. Unter `strict` ist das gehashte Objekt buchstaeblich
+            // unveraendert, also bleiben persistierte Journey-Kohorten vergleichbar.
+            ...(extensions.abstention === "strict" ? {} : { abstention: extensions.abstention }),
+            sort: extensions.sort,
+            complexityBias: extensions.complexityBias,
+            diversify: query.diversify,
+            minScore: query.minScore ?? null,
+            branchWeights: this.branchWeights,
+            boostWeights: this.config.boostWeights,
+            recencyHalfLifeDays: this.deps.recencyHalfLifeDays ?? DEFAULT_RECENCY_HALF_LIFE_DAYS,
+            clockEnabled: this.deps.clock !== undefined,
+            sparseVectorizerEnabled: this.deps.sparseVectorizer !== undefined,
+            graphProximityEnabled: this.deps.graphProximity !== undefined,
+            findabilityEnabled: this.deps.findability !== undefined,
+            targets,
+            repoPriorities,
+            relevancePolicies,
+        }));
+    }
+    async enrichFinalHits(groups, query, warnings, options) {
+        const provider = this.deps.graphEnrichment;
+        if (provider === undefined)
+            return;
+        const targets = groups.flatMap((group, groupIndex) => group.hits.map((hit, hitIndex) => ({
+            targetId: `group:${String(groupIndex)}:hit:${String(hitIndex)}`,
+            workspaceId: query.workspaceId,
+            generationId: hit.indexGeneration,
+            repoId: hit.repoId,
+            refId: hit.refId,
+            fileId: hit.fileId,
+            filePath: hit.filePath,
+            ...(hit.symbolId === undefined ? {} : { symbolId: hit.symbolId }),
+        })));
+        try {
+            const result = await provider.enrich({
+                includeContext: query.includeGraphContext,
+                includeLinked: query.includeLinked,
+                relationLimit: SEARCH_GRAPH_RELATION_LIMIT,
+                targets,
+            }, options);
+            options?.signal?.throwIfAborted();
+            const expectedIds = new Set(targets.map((target) => target.targetId));
+            const entries = new Map();
+            const duplicateIds = new Set();
+            const unexpectedIds = new Set();
+            for (const entry of result.entries) {
+                if (!expectedIds.has(entry.targetId)) {
+                    unexpectedIds.add(entry.targetId);
+                    continue;
+                }
+                if (entries.has(entry.targetId))
+                    duplicateIds.add(entry.targetId);
+                else
+                    entries.set(entry.targetId, entry);
+            }
+            const missingIds = [];
+            for (let groupIndex = 0; groupIndex < groups.length; groupIndex++) {
+                const group = groups[groupIndex];
+                for (let hitIndex = 0; hitIndex < group.hits.length; hitIndex++) {
+                    const hit = group.hits[hitIndex];
+                    const targetId = `group:${String(groupIndex)}:hit:${String(hitIndex)}`;
+                    const entry = duplicateIds.has(targetId) ? undefined : entries.get(targetId);
+                    if (entry === undefined)
+                        missingIds.push(targetId);
+                    const detail = `graph enrichment provider returned no unique result for final hit "${hit.chunkId}"`;
+                    if (query.includeGraphContext) {
+                        hit.graphContext =
+                            entry?.graphContext === undefined
+                                ? unavailableSearchGraphRelations("provider_result_missing", detail, SEARCH_GRAPH_RELATION_LIMIT)
+                                : createSearchGraphRelations(entry.graphContext.relations, entry.graphContext.omissions, SEARCH_GRAPH_RELATION_LIMIT);
+                    }
+                    if (query.includeLinked) {
+                        hit.linkedSymbols =
+                            entry?.linkedSymbols === undefined
+                                ? unavailableSearchGraphRelations("provider_result_missing", detail, SEARCH_GRAPH_RELATION_LIMIT)
+                                : createSearchGraphRelations(entry.linkedSymbols.relations, entry.linkedSymbols.omissions, SEARCH_GRAPH_RELATION_LIMIT);
+                    }
+                }
+            }
+            const providerWarnings = [...result.warnings]
+                .map(normalizeGraphProviderWarning)
+                .sort((left, right) => {
+                const byCode = compareCodepoints(left.code, right.code);
+                if (byCode !== 0)
+                    return byCode;
+                const byMessage = compareCodepoints(left.message, right.message);
+                return byMessage !== 0
+                    ? byMessage
+                    : compareCodepoints(JSON.stringify(left.details ?? {}), JSON.stringify(right.details ?? {}));
+            });
+            warnings.push(...providerWarnings.slice(0, SEARCH_GRAPH_PROVIDER_WARNING_LIMIT));
+            if (providerWarnings.length > SEARCH_GRAPH_PROVIDER_WARNING_LIMIT) {
+                warnings.push({
+                    code: "GRAPH_ENRICHMENT_WARNINGS_TRUNCATED",
+                    message: `${String(providerWarnings.length - SEARCH_GRAPH_PROVIDER_WARNING_LIMIT)} additional graph enrichment provider warning(s) were omitted by the response limit`,
+                    details: {
+                        warningLimit: SEARCH_GRAPH_PROVIDER_WARNING_LIMIT,
+                        omittedWarningCount: providerWarnings.length - SEARCH_GRAPH_PROVIDER_WARNING_LIMIT,
+                    },
+                });
+            }
+            if (missingIds.length > 0 || duplicateIds.size > 0 || unexpectedIds.size > 0) {
+                const missing = boundedDiagnosticIds(missingIds);
+                const duplicates = boundedDiagnosticIds([...duplicateIds]);
+                const unexpected = boundedDiagnosticIds([...unexpectedIds]);
+                warnings.push({
+                    code: "GRAPH_ENRICHMENT_INCOMPLETE",
+                    message: "the graph enrichment provider returned an incomplete or ambiguous batch; affected hits carry provider_result_missing omissions",
+                    details: {
+                        missingTargetIds: missing.ids,
+                        omittedMissingTargetIdCount: missing.omittedCount,
+                        duplicateTargetIds: duplicates.ids,
+                        omittedDuplicateTargetIdCount: duplicates.omittedCount,
+                        unexpectedTargetIds: unexpected.ids,
+                        omittedUnexpectedTargetIdCount: unexpected.omittedCount,
+                    },
+                });
+            }
+        }
+        catch (error) {
+            options?.signal?.throwIfAborted();
+            const message = error instanceof Error ? error.message : String(error);
+            const detail = boundSearchGraphDetail(`graph enrichment failed after ranking: ${message}`);
+            markFinalHitGraphUnavailable(groups, query, detail);
+            if (query.includeGraphContext) {
+                warnings.push({ code: "GRAPH_CONTEXT_UNAVAILABLE", message: detail });
+            }
+            if (query.includeLinked) {
+                warnings.push({ code: "LINKED_ARTIFACTS_UNAVAILABLE", message: detail });
+            }
+            this.deps.logger?.log({
+                timestamp: this.deps.clock?.nowIso() ?? "",
+                level: "warn",
+                component: "search",
+                event: "graph_enrichment_failed",
+                context: { message },
+            });
+        }
+    }
+    /**
+     * grep laeuft im selben Geltungsbereich wie `search`: Workspace aus den
+     * Vorgaben, wenn die Anfrage keinen nennt, und nur die Repositories der
+     * verdrahteten Ziele. Sonst faende dieselbe Oberflaeche mit demselben
+     * Aufrufer je nach Werkzeug verschiedene Mengen.
+     */
+    grep(request, options) {
+        return grepIndexedChunks(this.deps.vectorStore, uniqueSortedByCodepoints(this.deps.targets.map((target) => target.collection)), request, options, {
+            workspaceId: this.deps.defaults.workspaceId,
+            repoIds: uniqueSortedByCodepoints(this.deps.targets.flatMap((target) => target.repoIds)),
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Ein Ziel (= ein Embedding-Profil, eine Collection)
+    // -------------------------------------------------------------------------
+    async searchTarget(target, query, extensions, ledger, minScoreOrigin, options) {
+        const scope = {
+            workspaceId: query.workspaceId,
+            targetRepoIds: target.repoIds,
+        };
+        const requestedFilter = buildPayloadFilter(query.filters, scope);
+        // A ref-less request must not turn a locally recorded current corpus into
+        // an unbounded scan of every historical ref still present in the shared
+        // collection. Use every recorded ref in the effective repo scope. Doing
+        // this at the port boundary keeps non-CLI callers honest as well.
+        const inferredRefIds = query.filters.refIds.length === 0 && requestedFilter.emptyScopeReason === undefined
+            ? uniqueSortedByCodepoints((target.indexContexts ?? [])
+                .filter((context) => requestedFilter.scopeRepoIds.length === 0 ||
+                requestedFilter.scopeRepoIds.includes(context.repoId))
+                .map((context) => context.refId))
+            : [];
+        const effectiveRefIds = query.filters.refIds.length === 0 ? inferredRefIds : query.filters.refIds;
+        const built = query.filters.refIds.length === 0 && inferredRefIds.length > 0
+            ? buildPayloadFilter({ ...query.filters, refIds: inferredRefIds }, scope)
+            : requestedFilter;
+        // WP-178: Die zweite Verteidigungslinie prueft ab hier den WIRKSAMEN
+        // Bereich (Ziel geschnitten mit dem Repo-Filter der Anfrage), nicht mehr
+        // nur die Zieldeklaration. Ein Speicher, der den Payloadfilter ignoriert,
+        // lieferte sonst einen Treffer aus einem Repository, das der Nutzer
+        // ausdruecklich NICHT angefragt hat — waehrend `group.repoIds` das
+        // Gegenteil behauptet.
+        const effectiveScope = {
+            workspaceId: query.workspaceId,
+            targetRepoIds: built.scopeRepoIds,
+        };
+        if (built.emptyScopeReason !== undefined) {
+            // E4: Der Speicher wird NICHT gefragt — eine leere `in`-Liste waere
+            // kein Filter, sondern gar keiner, und die Suche liefe ueber die ganze
+            // Collection. Der leere Bereich steht stattdessen im Ledger.
+            ledger.add({
+                subjectKind: "search_candidate",
+                subjectId: target.embeddingProfileId,
+                reason: "excluded_by_configuration",
+                detail: built.emptyScopeReason,
+                recoverable: true,
+            });
+            return {
+                group: {
+                    embeddingProfileId: target.embeddingProfileId,
+                    repoIds: [],
+                    hits: [],
+                    rankNormalized: false,
+                    caveats: [built.emptyScopeReason],
+                    // E4: „nicht gesucht" ist im Ergebnis von „gesucht, nichts gefunden"
+                    // zu unterscheiden. Ohne diese Markierung sieht die Gruppe wie eine
+                    // leere Trefferliste aus, und die Findability-Sonde macht daraus
+                    // „das Symbol findet sich selbst nicht" — eine Aussage ueber den
+                    // Code, die auf keiner Beobachtung steht.
+                    notSearchedReason: built.emptyScopeReason,
+                },
+                refIds: new Set(),
+            };
+        }
+        // WP-176 (E4): Angefragte Repositories, die dieses Ziel gar nicht fuehrt,
+        // fielen bisher lautlos aus dem Durchschnitt. Nur der VOLLSTAENDIG leere
+        // Fall (oben) kam in den Ledger. Ein teilweiser Ausfall sieht damit wie
+        // eine vollstaendige Suche aus — die gefaehrlichere der beiden Formen,
+        // weil sie Treffer liefert und deshalb niemand nachfragt.
+        const outOfScope = built.outOfScopeRepoIds;
+        const caveats = built.residual.map((residual) => `filter "${residual.name}" was applied in-process, not in the store: ${residual.reason}`);
+        if (query.filters.refIds.length === 0 && inferredRefIds.length > 0) {
+            caveats.push(`the request omitted refs; this target was searched only across locally recorded refs [${inferredRefIds.join(", ")}]`);
+        }
+        if (outOfScope.length > 0) {
+            const detail = `the requested repositories [${outOfScope.join(", ")}] are not part of this target's repositories [${sortByCodepoints([...target.repoIds]).join(", ")}]; they were NOT searched here`;
+            caveats.push(detail);
+            for (const repoId of outOfScope) {
+                ledger.add({
+                    subjectKind: "search_candidate",
+                    subjectId: `${target.embeddingProfileId}:${repoId}`,
+                    reason: "excluded_by_configuration",
+                    detail,
+                    recoverable: true,
+                });
+            }
+        }
+        const pool = new Map();
+        const rejectedPointIds = new Set();
+        const active = branchesOfMode(extensions.mode);
+        const retrieval = await retrieveIndependentBranches({
+            vectorStore: this.deps.vectorStore,
+            target,
+            text: query.text,
+            filter: built.filter,
+            candidateLimit: query.candidateLimit,
+            mode: extensions.mode,
+            branchTimeoutMs: this.branchTimeoutMs,
+            ...(this.deps.sparseVectorizer === undefined
+                ? {}
+                : { sparseVectorizer: this.deps.sparseVectorizer }),
+        }, options);
+        caveats.push(...retrieval.caveats);
+        for (const skipped of retrieval.skipped)
+            ledger.add(skipped);
+        assertCompletedRetrieval(retrieval, target);
+        const { densePoints, sparsePoints, symbolPage, completedBranches, warnings: branchWarnings, } = retrieval;
+        this.collect(densePoints, pool, rejectedPointIds, ledger, (candidate, point) => {
+            candidate.denseScore = point.denseScore ?? point.score;
+        });
+        this.collect(sparsePoints, pool, rejectedPointIds, ledger, () => undefined);
+        // --- Abruf: Symbolzweig ----------------------------------------------
+        let symbolPointCount = 0;
+        let symbolLimitReached = false;
+        if (symbolPage !== undefined) {
+            const symbolPoints = symbolPage.points.map((point) => ({
+                id: point.id,
+                score: 0,
+                payload: point.payload,
+            }));
+            symbolPointCount = symbolPoints.length;
+            symbolLimitReached =
+                symbolPage.nextOffset !== undefined || symbolPoints.length >= query.candidateLimit;
+            this.collect(symbolPoints, pool, rejectedPointIds, ledger, () => undefined);
+            if (symbolPage.nextOffset !== undefined) {
+                ledger.add({
+                    subjectKind: "search_candidate",
+                    subjectId: `${target.collection}:symbol_scroll`,
+                    reason: "excluded_by_configuration",
+                    detail: `exact symbol-name scroll stopped at candidateLimit=${query.candidateLimit}; more exact matches exist in "${target.collection}"`,
+                    recoverable: true,
+                });
+            }
+        }
+        // --- Residuale Filter VOR jeder Rangfolge ------------------------------
+        // Ein Kandidat, der laut Anfrage ungueltig ist, darf weder Pool-IDF noch
+        // Zweigraenge, exakten Intent oder dessen Gewicht beeinflussen. Dadurch
+        // entsprechen alle erklaerten Raenge der Menge, die wirklich antworten
+        // durfte. `passesResidualFilters` wird genau einmal je Kandidat gerufen,
+        // also entsteht auch genau ein Ledger-Eintrag je Ausschluss.
+        const candidates = [...pool.values()].filter((candidate) => this.passesResidualFilters(candidate, query, extensions, effectiveScope, effectiveRefIds, ledger));
+        const eligibleIds = new Set(candidates.map((candidate) => candidate.pointId));
+        const denseRankedIds = [];
+        const denseSeen = new Set();
+        for (const point of densePoints) {
+            if (!eligibleIds.has(point.id) || denseSeen.has(point.id)) {
+                continue;
+            }
+            const candidate = pool.get(point.id);
+            if (candidate === undefined) {
+                continue;
+            }
+            denseSeen.add(point.id);
+            denseRankedIds.push(point.id);
+            candidate.denseRank = denseRankedIds.length;
+        }
+        // --- Rangfolge: lexikalisch (eigenes BM25 ueber den gueltigen Pool) ----
+        const lexicalRanker = new Bm25Ranker(candidates.map((candidate) => ({
+            id: candidate.pointId,
+            text: lexicalDocumentText(candidate.payload),
+        })));
+        const lexicalRanking = active.lexical && completedBranches.has("sparse") ? lexicalRanker.rank(query.text) : [];
+        const lexicalRankedIds = lexicalRanking.map((entry) => entry.id);
+        for (const entry of lexicalRanking) {
+            const candidate = pool.get(entry.id);
+            if (candidate !== undefined) {
+                candidate.lexicalScore = entry.score;
+                candidate.lexicalRank = entry.rank;
+            }
+        }
+        // --- Rangfolge: exakter Symbolname ------------------------------------
+        const symbolMatches = [];
+        for (const candidate of candidates) {
+            const match = matchSymbolName(candidate.payload, query.text);
+            if (match !== null) {
+                candidate.symbolMatchStrength = match.strength;
+                candidate.symbolMatchEvidence = match.evidence;
+                symbolMatches.push({
+                    id: candidate.pointId,
+                    strength: match.strength,
+                    repoId: candidate.payload.repo_id,
+                    refId: candidate.payload.ref_id,
+                    filePath: candidate.payload.file_path,
+                    startLine: candidate.payload.start_line,
+                });
+            }
+        }
+        symbolMatches.sort((a, b) => {
+            if (a.strength !== b.strength) {
+                return b.strength - a.strength;
+            }
+            const byRepo = compareCodepoints(a.repoId, b.repoId);
+            if (byRepo !== 0) {
+                return byRepo;
+            }
+            const byRef = compareCodepoints(a.refId, b.refId);
+            if (byRef !== 0) {
+                return byRef;
+            }
+            const byPath = compareCodepoints(a.filePath, b.filePath);
+            if (byPath !== 0) {
+                return byPath;
+            }
+            if (a.startLine !== b.startLine) {
+                return a.startLine - b.startLine;
+            }
+            return compareCodepoints(a.id, b.id);
+        });
+        // --- Fusion ------------------------------------------------------------
+        const available = {
+            dense: active.dense && completedBranches.has("dense"),
+            lexical: active.lexical && completedBranches.has("sparse"),
+            symbol: active.symbol && completedBranches.has("symbol"),
+        };
+        const inputs = [];
+        if (available.dense) {
+            inputs.push({ branch: "dense", rankedIds: denseRankedIds });
+        }
+        // WP-232: Bei klar deutsch formulierten NATUERLICHEN Fragen kann BM25 ein
+        // systematischer Gegenspieler des multilingualen Embeddings sein. Es wird
+        // aber nur dann weggelassen, wenn sein eigener Spitzenkandidat NICHT in
+        // den dichten Top 10 bestaetigt ist. So bleibt nuetzliche Uebereinstimmung
+        // (d1 und die deutsche INDEX-SHARING-Probe) erhalten, waehrend die
+        // gemessenen Fehlraenge d3/d4/d6 nicht mehr in die Fusion eingehen.
+        const omitLexicalForGermanQuestion = extensions.mode === "hybrid" &&
+            available.dense &&
+            available.lexical &&
+            shouldOmitUncorroboratedGermanLexicalBranch(query.text, denseRankedIds, lexicalRankedIds);
+        if (available.lexical && !omitLexicalForGermanQuestion) {
+            inputs.push({ branch: "lexical", rankedIds: lexicalRankedIds });
+        }
+        if (omitLexicalForGermanQuestion) {
+            caveats.push(`the lexical ranking branch did not participate because its top candidate was not corroborated in the dense top ${GERMAN_LEXICAL_CORROBORATION_DEPTH} for this German natural-language question; dense multilingual ranking remains active (WP-232)`);
+        }
+        const effectiveActive = {
+            ...available,
+            lexical: available.lexical && !omitLexicalForGermanQuestion,
+        };
+        const exactSymbolMatches = symbolMatches.filter((entry) => entry.strength === 1);
+        const exactSymbolIntent = available.symbol && exactSymbolMatches.length > 0 && this.branchWeights.symbol > 0;
+        const symbolRanking = exactSymbolIntent ? exactSymbolMatches : symbolMatches;
+        if (available.symbol) {
+            symbolRanking.forEach((entry, index) => {
+                const candidate = pool.get(entry.id);
+                if (candidate !== undefined) {
+                    candidate.symbolRank = index + 1;
+                }
+            });
+            inputs.push({ branch: "symbol", rankedIds: symbolRanking.map((entry) => entry.id) });
+        }
+        const effectiveBranchWeights = exactSymbolIntent
+            ? exactSymbolIntentBranchWeights(this.branchWeights, effectiveActive)
+            : this.branchWeights;
+        if (exactSymbolIntent) {
+            caveats.push(`exact symbol-name intent: the symbol RRF branch contains only ${exactSymbolMatches.length} character-identical match(es) and uses weight ${effectiveBranchWeights.symbol}; heuristic boost clamping remains unchanged`);
+        }
+        const fused = fuseRankings(inputs, effectiveBranchWeights);
+        const fusionById = new Map(fused.map((entry) => [entry.id, entry]));
+        // Kandidaten, die in KEINEM aktiven Zweig auftauchen, sind fuer diesen
+        // Modus schlicht nicht relevant. Sie verschwinden trotzdem nicht
+        // stillschweigend (E4).
+        for (const candidate of candidates) {
+            if (!fusionById.has(candidate.pointId)) {
+                ledger.addCandidate({
+                    subjectId: candidate.payload.chunk_id,
+                    path: candidate.payload.file_path,
+                    repoId: candidate.payload.repo_id,
+                    refId: candidate.payload.ref_id,
+                    reason: "excluded_by_configuration",
+                    detail: `no active ranking branch (mode "${extensions.mode}") produced a rank for this candidate`,
+                });
+            }
+        }
+        // --- Kandidaten mit Basisrang ------------------------------------------
+        const scored = [];
+        for (const entry of fused) {
+            const candidate = pool.get(entry.id);
+            if (candidate === undefined) {
+                continue;
+            }
+            scored.push({ candidate, baseScore: entry.normalized });
+        }
+        // --- Dedupe -------------------------------------------------------------
+        const deduped = dedupeCandidates(scored);
+        for (const group of deduped) {
+            for (const absorbed of group.absorbed) {
+                ledger.addCandidate({
+                    subjectId: absorbed.candidate.payload.chunk_id,
+                    path: absorbed.candidate.payload.file_path,
+                    repoId: absorbed.candidate.payload.repo_id,
+                    refId: absorbed.candidate.payload.ref_id,
+                    reason: "duplicate",
+                    detail: `merged into chunk "${group.primary.candidate.payload.chunk_id}" as a related fragment (same metrics_scope_id "${absorbed.candidate.payload.metrics_scope_id}")`,
+                });
+            }
+        }
+        // --- Diversifizierung ---------------------------------------------------
+        const penalties = query.diversify
+            ? assignDuplicatePenalties(deduped, (entry) => entry.primary.candidate.payload)
+            : deduped.map((entry) => ({ item: entry, penaltyRawValue: 0 }));
+        // --- Score-Zerlegung ----------------------------------------------------
+        const scoringContext = {
+            queryText: query.text,
+            weights: this.config.boostWeights,
+            complexityBias: extensions.complexityBias,
+            repoPriorities: this.deps.repoPriorities ?? {},
+            graphProximity: this.buildProximityMap(deduped),
+            ...(this.deps.clock === undefined ? {} : { nowEpochMs: this.deps.clock.nowEpochMs() }),
+            recencyHalfLifeDays: this.deps.recencyHalfLifeDays ?? DEFAULT_RECENCY_HALF_LIFE_DAYS,
+        };
+        let hits = [];
+        for (const penalized of penalties) {
+            const group = penalized.item;
+            const fusion = fusionById.get(group.primary.candidate.pointId);
+            const breakdown = assembleScoreBreakdown(group.primary.candidate, fusion, scoringContext, penalized.penaltyRawValue);
+            const minScore = query.minScore;
+            if (minScore !== undefined && breakdown.final < minScore) {
+                ledger.addCandidate({
+                    subjectId: group.primary.candidate.payload.chunk_id,
+                    path: group.primary.candidate.payload.file_path,
+                    repoId: group.primary.candidate.payload.repo_id,
+                    refId: group.primary.candidate.payload.ref_id,
+                    reason: "excluded_by_configuration",
+                    detail: `final score ${breakdown.final} is below the effective minScore ${minScore} (${minScoreOrigin})`,
+                });
+                continue;
+            }
+            hits.push(this.buildHit(group.primary.candidate, breakdown, group.dedupeKey, group.relatedFragments, target, extensions));
+        }
+        hits = sortHits(hits, extensions.sort);
+        let relevanceWarning;
+        // Das Verdikt gehoert an die Gruppe, nicht nur in eine Warnung. Bis Welle
+        // 14 war es ausschliesslich in `relevanceWarning.details` flachgeklopft —
+        // deshalb lasen zehn Stellen im Repository die Enthaltung aus der
+        // Listenlaenge statt aus der Entscheidung.
+        let relevanceVerdict;
+        const relevanceBinding = this.relevancePolicies.get(target.embeddingProfileId);
+        if (relevanceBinding === undefined && this.relevancePolicies.size > 0) {
+            const configuredEmbeddingProfileIds = sortByCodepoints([...this.relevancePolicies.keys()]);
+            const detail = `relevance policy was not evaluated because active embedding profile "${target.embeddingProfileId}" has no configured binding; configured profile keys: ${configuredEmbeddingProfileIds.join(", ")}; results were left unchanged`;
+            caveats.push(detail);
+            relevanceWarning = {
+                code: RELEVANCE_POLICY_NOT_EVALUATED_WARNING_CODE,
+                message: detail,
+                details: {
+                    status: "not_evaluated",
+                    basis: "policy_profile_mismatch",
+                    actualEmbeddingProfileId: target.embeddingProfileId,
+                    configuredEmbeddingProfileIds,
+                },
+            };
+            relevanceVerdict = {
+                abstention: extensions.abstention,
+                status: "not_evaluated",
+                basis: "policy_profile_mismatch",
+            };
+        }
+        else if (relevanceBinding !== undefined) {
+            const exactSymbolIds = new Set(exactSymbolMatches.map((exact) => exact.id));
+            const prerequisiteFailure = relevancePrerequisiteFailure({
+                binding: relevanceBinding,
+                embeddingProfileId: target.embeddingProfileId,
+                workspaceId: query.workspaceId,
+                collection: target.collection,
+                completedBranches,
+                exactSymbolEvidenceAvailable: active.symbol && exactSymbolIds.size > 0,
+                abstention: extensions.abstention,
+            });
+            if (prerequisiteFailure !== undefined) {
+                caveats.push(prerequisiteFailure.detail);
+                relevanceWarning = prerequisiteFailure.warning;
+                relevanceVerdict = prerequisiteFailure.verdict;
+            }
+            else {
+                // Die Schwellen wurden gegen das feste Praefix von jeweils Rang 50
+                // des dichten UND spaerlichen Abrufzweigs kalibriert. Der
+                // Ranking-Pool darf groesser sein, die Abwesenheitsevidenz aber nicht:
+                // sonst veraendert candidateLimit die Pool-IDF und damit bei
+                // identischer Anfrage die Ja/Nein-Antwort. Der Symbolabruf gehoert
+                // nicht zur IDF-Kalibrierung; ein exakter Name bleibt eigene direkte
+                // Evidenz.
+                // Residual ungueltige IDs sind bereits aus `eligibleIds` entfernt und
+                // werden innerhalb des festen Praefixes bewusst NICHT durch tiefere
+                // Kandidaten ersetzt.
+                const evidencePool = selectFixedRelevanceEvidencePool([
+                    { branch: "dense", candidateIds: densePoints.map((point) => point.id) },
+                    { branch: "sparse", candidateIds: sparsePoints.map((point) => point.id) },
+                ], eligibleIds, relevanceBinding.policy.denseReferenceRank);
+                const evidenceIds = [...evidencePool.candidateIds];
+                const evidenceIdSet = new Set(evidenceIds);
+                // Der exakte Symbolpfad bleibt direkte Evidenz, auch wenn sehr viele
+                // gleichartige Scroll-Treffer vor ihm liegen. Nur residual gueltige
+                // `symbolMatches` koennen hier auftauchen.
+                if (active.symbol) {
+                    for (const exactSymbolId of exactSymbolIds) {
+                        if (!evidenceIdSet.has(exactSymbolId)) {
+                            evidenceIdSet.add(exactSymbolId);
+                            evidenceIds.push(exactSymbolId);
+                        }
+                    }
+                }
+                const denseEvidenceIds = new Set(evidencePool.denseCandidateIds);
+                const relevanceDecision = decideResultRelevance(query.text, evidenceIds.flatMap((candidateId) => {
+                    const candidate = pool.get(candidateId);
+                    if (candidate === undefined) {
+                        return [];
+                    }
+                    return [
+                        {
+                            ...(denseEvidenceIds.has(candidateId) && candidate.denseScore !== undefined
+                                ? { denseScore: candidate.denseScore }
+                                : {}),
+                            lexicalText: lexicalDocumentText(candidate.payload),
+                            exactSymbolMatch: active.symbol && exactSymbolIds.has(candidate.pointId),
+                        },
+                    ];
+                }), relevanceBinding.policy);
+                relevanceVerdict = {
+                    abstention: extensions.abstention,
+                    status: relevanceDecision.status,
+                    basis: relevanceDecision.basis,
+                    calibrationId: relevanceBinding.policy.calibrationId,
+                };
+                if (relevanceDecision.status === "rejected") {
+                    const observedReferenceRank = relevanceDecision.denseReferenceRankObserved;
+                    const detail = `candidate rejected by relevance policy "${relevanceBinding.policy.calibrationId}": top dense ${relevanceDecision.topDenseScore ?? "none"} (minimum ${relevanceBinding.policy.minimumDenseScore}), spread between rank 1 and observed rank ${observedReferenceRank} ${relevanceDecision.denseSpread ?? "unavailable"} (minimum ${relevanceBinding.policy.minimumDenseSpread}), fixed per-branch candidate-evidence pool IDF coverage ${relevanceDecision.candidateIdfCoverage} across ${relevanceDecision.candidateEvidenceCount} candidates (minimum ${relevanceBinding.policy.minimumCandidateIdfCoverage}); all three non-symbol conditions are required`;
+                    // NUR `strict` verwirft. Unter `evidence` bleiben die Treffer
+                    // stehen und tragen das Verdikt mit — und dann darf auch KEIN
+                    // Ledger-Eintrag geschrieben werden: ein Eintrag ueber einen
+                    // Gegenstand, der im Ergebnis steht, ist in diesem Repository ein
+                    // dokumentierter E4-Defekt (WP-142).
+                    if (extensions.abstention === "strict") {
+                        for (const dropped of hits) {
+                            ledger.addCandidate({
+                                subjectId: dropped.chunkId,
+                                path: dropped.filePath,
+                                repoId: dropped.repoId,
+                                refId: dropped.refId,
+                                // NICHT `excluded_by_configuration`: es wurde nichts
+                                // wegkonfiguriert, und der Kandidat ist nicht durch Filter
+                                // oder Budget gefallen. Ohne eigenen Grund liesse sich eine
+                                // Enthaltung nicht von einem Score-Schwellwert trennen (E4).
+                                reason: "relevance_policy_rejected",
+                                detail,
+                            });
+                        }
+                        hits = [];
+                    }
+                    // Vorbehalt und Warnung sind in BEIDEN Verhalten byte-identisch:
+                    // das Urteil aendert sich nicht, nur was mit den Treffern geschieht.
+                    caveats.push(detail);
+                    relevanceWarning = {
+                        code: NO_SUFFICIENT_MATCH_WARNING_CODE,
+                        message: `No sufficiently relevant result for embedding profile "${target.embeddingProfileId}": without an exact symbol name, the dense top score, gap to the fixed reference rank and IDF-weighted query coverage must jointly support the verdict within the fixed evidence pool`,
+                        details: {
+                            embeddingProfileId: target.embeddingProfileId,
+                            collection: target.collection,
+                            ...relevanceDecision,
+                        },
+                    };
+                }
+                else if (relevanceDecision.status === "not_evaluated") {
+                    const detail = `relevance policy "${relevanceBinding.policy.calibrationId}" was not evaluated: the deepest dense rank actually observed was ${relevanceDecision.deepestDenseRankObserved}, so calibrated reference rank ${relevanceBinding.policy.denseReferenceRank} was not observed; results were left unchanged`;
+                    caveats.push(detail);
+                    relevanceWarning = {
+                        code: RELEVANCE_POLICY_NOT_EVALUATED_WARNING_CODE,
+                        message: detail,
+                        details: {
+                            embeddingProfileId: target.embeddingProfileId,
+                            collection: target.collection,
+                            ...relevanceDecision,
+                        },
+                    };
+                }
+            }
+        }
+        const qualifiedHitCount = hits.length;
+        const topScoreGap = hits.length < 2
+            ? null
+            : hits[0].score.final - hits[1].score.final;
+        if (hits.length > query.limit) {
+            for (const dropped of hits.slice(query.limit)) {
+                ledger.addCandidate({
+                    subjectId: dropped.chunkId,
+                    path: dropped.filePath,
+                    repoId: dropped.repoId,
+                    refId: dropped.refId,
+                    reason: "excluded_by_configuration",
+                    detail: `final score ${dropped.score.final} ranked below the requested limit of ${query.limit} results`,
+                });
+            }
+            hits = hits.slice(0, query.limit);
+        }
+        hits = assignRanks(hits);
+        const uniqueEligibleFileCount = new Set(candidates.map((candidate) => `${candidate.payload.repo_id}\u001f${candidate.payload.ref_id}\u001f${candidate.payload.file_path}`)).size;
+        const uniqueEligibleSymbolCount = new Set(candidates.flatMap((candidate) => candidate.payload.symbol_id === undefined
+            ? []
+            : [
+                `${candidate.payload.repo_id}\u001f${candidate.payload.ref_id}\u001f${candidate.payload.symbol_id}`,
+            ])).size;
+        const eligibleFileDispersion = candidates.length <= 1 ? 0 : (uniqueEligibleFileCount - 1) / (candidates.length - 1);
+        const { contexts: scopedIndexContexts, corpusRevisionFingerprint, warning: indexContextWarning, } = this.indexContextProvenance(target, built.scopeRepoIds, effectiveRefIds, candidates, query.filters.refIds.length === 0);
+        // WP-189: Der Vertrag von `SearchHitGroupV1.repoIds` lautet „Repositories,
+        // die zu dieser Gruppe BEITRAGEN". Hier stand der erlaubte Bereich — also
+        // eine Aussage ueber die Anfrage, ausgegeben als Aussage ueber das
+        // Ergebnis. Bei drei erlaubten und einem liefernden Repository nannte die
+        // Gruppe drei Herkuenfte, von denen zwei nichts beigetragen hatten.
+        const contributing = uniqueSortedByCodepoints(hits.map((hit) => hit.repoId));
+        return {
+            group: {
+                embeddingProfileId: target.embeddingProfileId,
+                // A completed local state proves provenance for an empty result, but
+                // must never lend its generation to a returned legacy candidate that
+                // did not carry `generation_id` itself. The display field may retain
+                // the legacy dependency fallback; corpus provenance below never does.
+                indexGenerations: uniqueSortedByCodepoints(candidates.length === 0
+                    ? scopedIndexContexts.map((context) => context.generationId)
+                    : candidates.map((candidate) => this.indexGenerationOf(candidate))),
+                ...(corpusRevisionFingerprint === undefined ? {} : { corpusRevisionFingerprint }),
+                repoIds: contributing,
+                hits,
+                rankNormalized: false,
+                caveats,
+                ...(relevanceVerdict === undefined ? {} : { relevanceDecision: relevanceVerdict }),
+                retrieval: {
+                    branchCandidateCounts: {
+                        dense: densePoints.length,
+                        sparse: sparsePoints.length,
+                        symbol: symbolPointCount,
+                    },
+                    uniqueRetrievedCandidateCount: pool.size,
+                    eligibleCandidateCount: candidates.length,
+                    rankedCandidateCount: fused.length,
+                    deduplicatedCandidateCount: deduped.length,
+                    qualifiedHitCount,
+                    returnedHitCount: hits.length,
+                    uniqueEligibleFileCount,
+                    uniqueEligibleSymbolCount,
+                    eligibleFileDispersion,
+                    topScoreGap,
+                    candidateLimitReached: densePoints.length >= query.candidateLimit ||
+                        sparsePoints.length >= query.candidateLimit ||
+                        symbolLimitReached,
+                },
+            },
+            refIds: new Set(hits.map((hit) => hit.refId)),
+            ...(relevanceWarning === undefined ? {} : { relevanceWarning }),
+            ...(indexContextWarning === undefined ? {} : { indexContextWarning }),
+            ...(branchWarnings.length === 0 ? {} : { branchWarnings }),
+        };
+    }
+    /** Uebernimmt Speicherpunkte in den Kandidatenpool; unbrauchbare landen im Ledger. */
+    collect(points, pool, rejectedPointIds, ledger, onCandidate) {
+        points.forEach((point) => {
+            if (rejectedPointIds.has(point.id)) {
+                return;
+            }
+            const existing = pool.get(point.id);
+            if (existing !== undefined) {
+                onCandidate(existing, point);
+                return;
+            }
+            const result = candidateFromPoint(point);
+            if (!result.ok) {
+                rejectedPointIds.add(point.id);
+                ledger.addCandidate({
+                    subjectId: point.id,
+                    reason: "missing_index_entry",
+                    detail: `point "${point.id}" could not be read as a code chunk: ${result.reason}`,
+                });
+                return;
+            }
+            pool.set(point.id, result.candidate);
+            onCandidate(result.candidate, point);
+        });
+    }
+    /** Pfad-Globs und Findability — die Filter, die der Speicher nicht kennt. */
+    passesResidualFilters(candidate, query, extensions, scope, effectiveRefIds, ledger) {
+        const { payload } = candidate;
+        // Der Geltungsbereich steht bereits im Speicherfilter. Er wird hier ein
+        // ZWEITES Mal geprueft, weil ein Speicher, der den Filter nicht oder
+        // anders auswertet, sonst fremden Inhalt als eigenen ausliefern wuerde —
+        // und das waere kein ungenaues Ranking, sondern ein Datenleck.
+        if (payload.workspace_id !== scope.workspaceId) {
+            ledger.addCandidate({
+                subjectId: payload.chunk_id,
+                path: payload.file_path,
+                repoId: payload.repo_id,
+                refId: payload.ref_id,
+                reason: "excluded_by_configuration",
+                detail: `candidate belongs to workspace "${payload.workspace_id}", but the query is scoped to workspace "${scope.workspaceId}"`,
+            });
+            return false;
+        }
+        const targetRepoIds = scope.targetRepoIds ?? [];
+        if (targetRepoIds.length > 0 && !targetRepoIds.includes(payload.repo_id)) {
+            ledger.addCandidate({
+                subjectId: payload.chunk_id,
+                path: payload.file_path,
+                repoId: payload.repo_id,
+                refId: payload.ref_id,
+                reason: "excluded_by_configuration",
+                detail: `candidate belongs to repository "${payload.repo_id}", which is not one of this target's repositories [${sortByCodepoints([...targetRepoIds]).join(", ")}]`,
+            });
+            return false;
+        }
+        if (effectiveRefIds.length > 0 && !effectiveRefIds.includes(payload.ref_id)) {
+            ledger.addCandidate({
+                subjectId: payload.chunk_id,
+                path: payload.file_path,
+                repoId: payload.repo_id,
+                refId: payload.ref_id,
+                reason: "excluded_by_configuration",
+                detail: `candidate belongs to ref "${payload.ref_id}", which is not one of the effective refs [${sortByCodepoints([...effectiveRefIds]).join(", ")}]`,
+            });
+            return false;
+        }
+        if (!isPathSelected(payload.file_path, query.filters.pathGlobs, extensions.pathExcludes)) {
+            ledger.addCandidate({
+                subjectId: payload.chunk_id,
+                path: payload.file_path,
+                repoId: payload.repo_id,
+                refId: payload.ref_id,
+                reason: "excluded_by_configuration",
+                detail: `path "${payload.file_path}" does not pass the include/exclude globs (include: [${query.filters.pathGlobs.join(", ")}], exclude: [${extensions.pathExcludes.join(", ")}])`,
+            });
+            return false;
+        }
+        const findabilityFilter = query.filters.findability;
+        const lookup = this.deps.findability;
+        if (findabilityFilter !== undefined && lookup !== undefined) {
+            const summary = payload.symbol_id === undefined ? undefined : lookup(payload.symbol_id);
+            if (summary === undefined) {
+                ledger.addCandidate({
+                    subjectId: payload.chunk_id,
+                    path: payload.file_path,
+                    repoId: payload.repo_id,
+                    refId: payload.ref_id,
+                    reason: "missing_index_entry",
+                    detail: "a findability filter was requested but no findability record exists for this symbol",
+                    recoverable: true,
+                });
+                return false;
+            }
+            const { minScore, maxScore, causes } = findabilityFilter;
+            const failsMin = minScore !== undefined && summary.score < minScore;
+            const failsMax = maxScore !== undefined && summary.score > maxScore;
+            const failsCause = causes !== undefined &&
+                causes.length > 0 &&
+                (summary.primaryCause === undefined || !causes.includes(summary.primaryCause));
+            if (failsMin || failsMax || failsCause) {
+                ledger.addCandidate({
+                    subjectId: payload.chunk_id,
+                    path: payload.file_path,
+                    repoId: payload.repo_id,
+                    refId: payload.ref_id,
+                    reason: "excluded_by_configuration",
+                    detail: `findability score ${summary.score} / cause "${summary.primaryCause ?? "none"}" does not satisfy the requested findability filter`,
+                });
+                return false;
+            }
+        }
+        return true;
+    }
+    buildProximityMap(deduped) {
+        const map = new Map();
+        const lookup = this.deps.graphProximity;
+        if (lookup === undefined) {
+            return map;
+        }
+        for (const group of deduped) {
+            const symbolId = group.primary.candidate.payload.symbol_id;
+            if (symbolId === undefined || map.has(symbolId)) {
+                continue;
+            }
+            const value = lookup(symbolId);
+            if (value !== undefined) {
+                map.set(symbolId, value);
+            }
+        }
+        return map;
+    }
+    buildHit(candidate, score, dedupeKey, relatedFragments, target, extensions) {
+        const { payload } = candidate;
+        const findabilitySummary = payload.symbol_id === undefined ? undefined : this.deps.findability?.(payload.symbol_id);
+        const contentRequested = extensions.includeContent;
+        const hasContent = payload.content !== "";
+        const complexity = this.complexityOf(candidate);
+        return {
+            schemaVersion: 1,
+            // Der endgueltige Rang wird nach der Sortierung gesetzt (`assignRanks`);
+            // bis dahin ist 0 ein bewusst ungueltiger Platzhalter, kein Rang 1.
+            rank: 0,
+            repoId: payload.repo_id,
+            repoLabel: payload.repo_label,
+            refId: payload.ref_id,
+            refName: payload.ref_name,
+            ...(payload.commit_sha === undefined ? {} : { commitSha: payload.commit_sha }),
+            fileId: payload.file_id,
+            filePath: payload.file_path,
+            range: {
+                startLine: payload.start_line,
+                endLine: payload.end_line,
+                startByte: payload.start_byte,
+                endByte: payload.end_byte,
+            },
+            language: payload.language,
+            parseQuality: payload.parse_quality,
+            chunkId: payload.chunk_id,
+            chunkKind: payload.chunk_kind,
+            ...(payload.fragment_index === undefined ? {} : { fragmentIndex: payload.fragment_index }),
+            ...(payload.fragment_count === undefined ? {} : { fragmentCount: payload.fragment_count }),
+            ...(payload.symbol_id === undefined ? {} : { symbolId: payload.symbol_id }),
+            ...(payload.symbol_name === undefined ? {} : { symbolName: payload.symbol_name }),
+            ...(payload.symbol_fqn === undefined ? {} : { symbolFqn: payload.symbol_fqn }),
+            ...(payload.symbol_kind === undefined ? {} : { symbolKind: payload.symbol_kind }),
+            ...(payload.signature === undefined ? {} : { signature: payload.signature }),
+            score,
+            dedupeKey,
+            relatedFragments,
+            embeddingProfileId: target.embeddingProfileId,
+            indexGeneration: this.indexGenerationOf(candidate),
+            ...(complexity === undefined ? {} : { complexity }),
+            ...(findabilitySummary === undefined ? {} : { findability: findabilitySummary }),
+            ...(contentRequested && hasContent ? { content: payload.content } : {}),
+            ...(contentRequested && !hasContent
+                ? {
+                    contentOmittedReason: "the stored chunk payload carries no content (indexed without content, or content stripped at index time)",
+                }
+                : {}),
+            ...(candidate.substitutedFields.length === 0
+                ? {}
+                : { incompletePayloadFields: [...candidate.substitutedFields] }),
+        };
+    }
+    indexGenerationOf(candidate) {
+        return this.rawIndexGenerationOf(candidate) ?? this.deps.indexGeneration ?? "unknown";
+    }
+    /** Persisted candidate provenance; display fallbacks are deliberately excluded. */
+    rawIndexGenerationOf(candidate) {
+        return readRawString(candidate.raw, "generation_id");
+    }
+    indexContextProvenance(target, scopeRepoIds, scopedRefIds, candidates, refScopeWasImplicit) {
+        const contexts = (target.indexContexts ?? []).filter((context) => scopeRepoIds.includes(context.repoId) &&
+            (scopedRefIds.length === 0 || scopedRefIds.includes(context.refId)));
+        const completedContextExists = (repoId, refId, generationId) => contexts.some((context) => context.outcome === "completed" &&
+            context.repoId === repoId &&
+            (refId === undefined || context.refId === refId) &&
+            (generationId === undefined || context.generationId === generationId));
+        // An implicit scope represents "the recorded current ref(s) of every
+        // selected repository", so every repository needs a completed context.
+        // Explicit repo-qualified ref IDs instead form real repo/ref pairs. They
+        // are not a Cartesian product: repo-a:main does not need to exist in
+        // repo-b merely because both repos and both refs were selected.
+        const hasCompleteScopeCoverage = contexts.length > 0 &&
+            (refScopeWasImplicit
+                ? scopeRepoIds.every((repoId) => completedContextExists(repoId))
+                : scopedRefIds.every((refId) => contexts.some((context) => context.outcome === "completed" && context.refId === refId)));
+        const candidatesHaveCompletedContext = candidates.every((candidate) => {
+            const rawGenerationId = this.rawIndexGenerationOf(candidate);
+            return (rawGenerationId !== undefined &&
+                completedContextExists(candidate.payload.repo_id, candidate.payload.ref_id, rawGenerationId));
+        });
+        const incomplete = target.indexContexts !== undefined &&
+            (!hasCompleteScopeCoverage ||
+                !candidatesHaveCompletedContext ||
+                contexts.some((context) => context.outcome !== "completed" || context.corpusRevisionFingerprint === undefined));
+        if (!incomplete) {
+            if (target.indexContexts === undefined)
+                return { contexts };
+            const corpusContexts = contexts
+                .map((context) => ({
+                repoId: context.repoId,
+                refId: context.refId,
+                generationId: context.generationId,
+                corpusRevisionFingerprint: context.corpusRevisionFingerprint,
+            }))
+                .sort((left, right) => compareCodepoints(canonicalJson(left), canonicalJson(right)));
+            return {
+                contexts,
+                corpusRevisionFingerprint: sha256Hex(canonicalJson({
+                    schemaVersion: 1,
+                    embeddingProfileId: target.embeddingProfileId,
+                    contexts: corpusContexts,
+                })),
+            };
+        }
+        return {
+            contexts,
+            warning: {
+                code: INDEX_CONTEXT_INCOMPLETE_WARNING_CODE,
+                message: `index completion could not be verified for embedding profile "${target.embeddingProfileId}"; ` +
+                    "hits remain usable, but this search is not healthy product-complexity evidence",
+                details: {
+                    embeddingProfileId: target.embeddingProfileId,
+                    observedOutcomes: uniqueSortedByCodepoints(contexts.map((context) => context.outcome)),
+                },
+            },
+        };
+    }
+    complexityOf(candidate) {
+        const { payload } = candidate;
+        const values = {
+            ...(payload.cyclomatic_classic === undefined
+                ? {}
+                : { cyclomaticClassic: payload.cyclomatic_classic }),
+            ...(payload.cyclomatic_extended === undefined
+                ? {}
+                : { cyclomaticExtended: payload.cyclomatic_extended }),
+            ...(payload.cognitive === undefined ? {} : { cognitive: payload.cognitive }),
+            ...(payload.max_nesting === undefined ? {} : { maxNesting: payload.max_nesting }),
+            ...(payload.sloc === undefined ? {} : { sloc: payload.sloc }),
+            ...(payload.halstead_volume === undefined ? {} : { halsteadVolume: payload.halstead_volume }),
+            ...(payload.maintainability_index === undefined
+                ? {}
+                : { maintainabilityIndex: payload.maintainability_index }),
+            ...(payload.risk_score === undefined ? {} : { riskScore: payload.risk_score }),
+        };
+        if (Object.keys(values).length === 0) {
+            return undefined;
+        }
+        return {
+            metricsScope: payload.metrics_scope,
+            metricsScopeId: payload.metrics_scope_id,
+            metricsVersion: payload.metrics_version,
+            ...values,
+        };
+    }
+}
+/** Kleiner Bequemlichkeits-Konstruktor. */
+export function createHybridSearchEngine(deps) {
+    return new HybridSearchEngine(deps);
+}
+function markFinalHitGraphUnavailable(groups, query, detail) {
+    for (const group of groups) {
+        for (const hit of group.hits) {
+            if (query.includeGraphContext) {
+                hit.graphContext = unavailableSearchGraphRelations("graph_unavailable", detail);
+            }
+            if (query.includeLinked) {
+                hit.linkedSymbols = unavailableSearchGraphRelations("graph_unavailable", detail);
+            }
+        }
+    }
+}
+//# sourceMappingURL=engine.js.map