@untangle-code/search 0.0.0-stage → 0.1.1

package/dist/retrieval.js

@@ -0,0 +1,182 @@
+/** Independent recall branches, bounded provider calls and deterministic failure diagnostics. */
+import { UntangleError, compareCodepoints, isUntangleError, } from "@untangle-code/domain";
+import { withSearchBranchDeadline } from "./deadline.js";
+import { buildSymbolNameFilter } from "./filter.js";
+import { symbolNameFilterCandidates } from "./symbol-match.js";
+/** The mode controls both recall and ranking, so it has one shared definition. */
+export function branchesOfMode(mode) {
+    switch (mode) {
+        case "semantic":
+            return { dense: true, lexical: false, symbol: false };
+        case "lexical":
+            return { dense: false, lexical: true, symbol: false };
+        case "symbol":
+            return { dense: false, lexical: false, symbol: true };
+        case "hybrid":
+            return { dense: true, lexical: true, symbol: true };
+    }
+}
+/** Cancellation is control flow, never a degraded retrieval result. */
+export function rethrowCancellation(error, options) {
+    options?.signal?.throwIfAborted();
+    if ((isUntangleError(error) && error.code === "JOB_CANCELLED") ||
+        (error instanceof Error && error.name === "AbortError")) {
+        throw error;
+    }
+}
+async function retrieveDense(request, options) {
+    const { target } = request;
+    const preparedQuery = `${target.embedder.profile.queryPrefix}${request.text}`;
+    const dense = await target.embedder.embedQuery(preparedQuery, options);
+    options.signal?.throwIfAborted();
+    return request.vectorStore.hybridQuery(target.collection, {
+        dense,
+        filter: request.filter,
+        limit: request.candidateLimit,
+        candidateLimit: request.candidateLimit,
+        withPayload: true,
+    }, options);
+}
+async function retrieveSparse(request, options) {
+    if (request.sparseVectorizer === undefined) {
+        throw new UntangleError("INDEX_INCOMPLETE", "no sparse vectorizer is wired", {
+            operation: "search_sparse_retrieval",
+        });
+    }
+    return request.vectorStore.hybridQuery(request.target.collection, {
+        sparse: request.sparseVectorizer(request.text),
+        filter: request.filter,
+        limit: request.candidateLimit,
+        candidateLimit: request.candidateLimit,
+        withPayload: true,
+    }, options);
+}
+async function retrieveSymbol(request, options) {
+    const filter = buildSymbolNameFilter(request.filter, symbolNameFilterCandidates(request.text));
+    if (filter === undefined)
+        return { points: [] };
+    return request.vectorStore.scroll(request.target.collection, { filter, limit: request.candidateLimit }, options);
+}
+/** Each branch produces an explicit outcome; a provider failure does not cancel its peers. */
+async function executeBranch(branch, enabled, request, retrieve, options) {
+    if (!enabled)
+        return { branch, status: "not_requested" };
+    try {
+        const result = await withSearchBranchDeadline(branch, request.mode === "hybrid" ? request.branchTimeoutMs : undefined, retrieve.bind(undefined, request), options, request.vectorStore.backend === "lancedb" ? "LANCEDB_UNAVAILABLE" : "QDRANT_UNAVAILABLE");
+        options.signal?.throwIfAborted();
+        return { branch, status: "succeeded", result };
+    }
+    catch (error) {
+        rethrowCancellation(error, options);
+        return {
+            branch,
+            status: "failed",
+            error: isUntangleError(error) || branch === "dense" || request.vectorStore.backend !== "lancedb"
+                ? error
+                : new UntangleError("LANCEDB_UNAVAILABLE", error instanceof Error ? error.message : String(error), { operation: "search_retrieval", retryable: true, cause: error }),
+        };
+    }
+}
+function branchResult(outcome) {
+    return outcome.status === "succeeded" ? outcome.result : undefined;
+}
+function isFailedBranch(outcome) {
+    return outcome.status === "failed";
+}
+function branchFailureCode(failure) {
+    if (failure !== undefined && isUntangleError(failure.error))
+        return failure.error.code;
+    return failure?.branch === "dense" ? "EMBEDDING_UNAVAILABLE" : "QDRANT_UNAVAILABLE";
+}
+function timeoutDetails(error) {
+    if (!isUntangleError(error) || error.context["timedOut"] !== true)
+        return {};
+    return { timedOut: true, timeoutMs: error.context["timeoutMs"] };
+}
+/** Build evidence once in branch-name order, independent of completion timing. */
+function failureDiagnostics(target, failures) {
+    const warnings = [];
+    const caveats = [];
+    const skipped = [];
+    for (const failure of failures) {
+        const { branch, error } = failure;
+        const message = error instanceof Error ? error.message : String(error);
+        const detail = `profile "${target.embeddingProfileId}" retrieval branch "${branch}" failed: ${message}`;
+        const timeout = timeoutDetails(error);
+        caveats.push(detail);
+        warnings.push({
+            code: "SEARCH_BRANCH_UNAVAILABLE",
+            message: detail,
+            details: {
+                embeddingProfileId: target.embeddingProfileId,
+                collection: target.collection,
+                branch,
+                causeCode: branchFailureCode(failure),
+                ...timeout,
+            },
+        });
+        if (timeout["timedOut"] === true) {
+            warnings.push({
+                code: "SEARCH_BRANCH_TIMEOUT",
+                message: detail,
+                details: { branch, timeoutMs: timeout["timeoutMs"] },
+            });
+        }
+        skipped.push({
+            subjectKind: "search_candidate",
+            subjectId: `${target.embeddingProfileId}:${branch}`,
+            reason: "provider_unavailable",
+            detail,
+            recoverable: true,
+        });
+    }
+    return { warnings, caveats, skipped };
+}
+/** Return all requested branch outcomes in fixed dense/sparse/symbol order. */
+export async function retrieveIndependentBranches(request, options) {
+    options?.signal?.throwIfAborted();
+    const active = branchesOfMode(request.mode);
+    const controller = new AbortController();
+    const linkedOptions = {
+        ...options,
+        signal: options?.signal === undefined
+            ? controller.signal
+            : AbortSignal.any([options.signal, controller.signal]),
+    };
+    const [dense, sparse, symbol] = await Promise.all([
+        executeBranch("dense", active.dense, request, retrieveDense, linkedOptions),
+        executeBranch("sparse", active.lexical, request, retrieveSparse, linkedOptions),
+        executeBranch("symbol", active.symbol, request, retrieveSymbol, linkedOptions),
+    ]).finally(() => controller.abort());
+    options?.signal?.throwIfAborted();
+    const outcomes = [dense, sparse, symbol];
+    const failures = outcomes
+        .filter(isFailedBranch)
+        .sort((left, right) => compareCodepoints(left.branch, right.branch));
+    const completedBranches = new Set(outcomes.filter((outcome) => outcome.status === "succeeded").map((outcome) => outcome.branch));
+    const symbolPage = branchResult(symbol);
+    return {
+        densePoints: branchResult(dense) ?? [],
+        sparsePoints: branchResult(sparse) ?? [],
+        ...(symbolPage === undefined ? {} : { symbolPage }),
+        completedBranches,
+        failures,
+        ...failureDiagnostics(request.target, failures),
+    };
+}
+/** The caller first records diagnostics, then distinguishes total failure from empty success. */
+export function assertCompletedRetrieval(result, target) {
+    if (result.completedBranches.size > 0)
+        return;
+    const first = result.failures[0];
+    throw new UntangleError(branchFailureCode(first), `all requested retrieval branches failed for profile "${target.embeddingProfileId}": ${result.warnings.map((warning) => warning.message).join("; ")}`, {
+        operation: "search_retrieval",
+        retryable: result.failures.some(({ error }) => !isUntangleError(error) || error.retryable),
+        context: {
+            collection: target.collection,
+            failedBranches: result.failures.map(({ branch }) => branch),
+        },
+        cause: first?.error,
+    });
+}
+//# sourceMappingURL=retrieval.js.map

package/dist/retrieval.js.map

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

package/dist/scoring.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Score-Zerlegung (spec.md §13.3).
+ *
+ * Das ist keine Debug-Ausgabe. Die Zerlegung ist oeffentliche API und die
+ * Grundlage der Findability-Diagnose (vision.md §1d): ohne sie laesst sich
+ * „der richtige Treffer rankt niedrig" nicht von „es gibt keinen Treffer"
+ * unterscheiden, und genau diese Unterscheidung ist die Aussage ueber den
+ * Code, nicht ueber die Suche.
+ *
+ * Aufbau:
+ *
+ *     final = base_hybrid
+ *           + exact_symbol_boost + exact_path_boost + repo_priority_boost
+ *           + graph_proximity_boost + recency_boost
+ *           + complexity_modifier
+ *           - duplicate_penalty
+ *
+ * Jeder Bestandteil traegt `rawValue` (das normalisierte Signal), `weight`
+ * (das Gewicht aus der Konfiguration) und `contribution = rawValue * weight`.
+ * `validateScoreBreakdown()` aus der Domain prueft genau diese Identitaet und
+ * die Summenprobe — die Tests dieses Pakets rufen sie auf jedem erzeugten
+ * Treffer auf.
+ *
+ * BEGRENZUNG DER BOOSTS (spec.md §13.3: „Heuristische Boosts DUERFEN
+ * Dense/BM25 nicht vollstaendig ueberstimmen"): Uebersteigt die Summe der
+ * Betraege aller Nicht-Basis-Bestandteile den Anteil {@link MAX_BOOST_SHARE}
+ * des Basisbetrags, werden ALLE Nicht-Basis-Gewichte mit demselben Faktor
+ * verkleinert und `clamped`/`clampReason` gesetzt. Verkleinert wird das
+ * GEWICHT, nicht der Beitrag: nur so bleibt `contribution = rawValue * weight`
+ * wahr und das Signal (`rawValue`) sichtbar.
+ */
+import type { CodeChunkPayloadV1, ScoreBreakdownV1, ScoreComponentV1 } from "@untangle-code/domain";
+import type { FusionResult } from "./fusion.js";
+import type { SearchCandidate } from "./payload.js";
+import type { ComplexityBias } from "./types.js";
+/**
+ * Hoechster zulaessiger Anteil aller Boosts/Strafen am Basisscore.
+ *
+ * 0.5 heisst: die Heuristik darf einen Treffer um hoechstens die Haelfte
+ * seines Basisscores verschieben. Damit bleibt der Basisanteil (`baseShare`
+ * aus `validateScoreBreakdown`) immer bei mindestens 1/1.5 ≈ 0.667 — der
+ * Basiszweig behaelt also strukturell die Mehrheit. Der Wert ist eine
+ * Politik-Entscheidung dieses Pakets und hier bewusst als benannte Konstante
+ * sichtbar statt als Zahl im Code verstreut.
+ */
+export declare const MAX_BOOST_SHARE = 0.5;
+/**
+ * Referenzwert der kognitiven Komplexitaet fuer den Komplexitaets-Modifikator.
+ * 25 ist der Punkt, ab dem der Modifikator seinen vollen Ausschlag erreicht;
+ * er ist eine Skalierungsgroesse fuer die Rangfolge und ausdruecklich KEINE
+ * Qualitaetsschwelle (Schwellen gehoeren in die Quality Gate, spec.md §18).
+ */
+export declare const COMPLEXITY_REFERENCE_COGNITIVE = 25;
+/** Gewichte der additiven Score-Bestandteile (Form aus `SearchConfig`). */
+export interface BoostWeights {
+    exactSymbol: number;
+    exactPath: number;
+    repoPriority: number;
+    graphProximity: number;
+    recency: number;
+    duplicatePenalty: number;
+}
+/** Gewicht des Komplexitaets-Modifikators, wenn die Anfrage ihn anfordert. */
+export declare const COMPLEXITY_MODIFIER_WEIGHT = 0.1;
+/** Alles, was zur Bewertung eines einzelnen Kandidaten gebraucht wird. */
+export interface ScoringContext {
+    queryText: string;
+    weights: BoostWeights;
+    complexityBias: ComplexityBias;
+    /** Repo-Prioritaet in [0, 1] je `repo_id`; fehlt = kein Bestandteil. */
+    repoPriorities: Readonly<Record<string, number>>;
+    /** Graph-Naehe in [0, 1] je `symbol_id`; fehlt = kein Bestandteil. */
+    graphProximity: ReadonlyMap<string, number>;
+    /** „Jetzt" in Epoch-Millisekunden, ueber den Clock-Port bezogen. */
+    nowEpochMs?: number;
+    /** Halbwertszeit des Recency-Boosts in Tagen. */
+    recencyHalfLifeDays: number;
+}
+/** Zeitzerfall in [0, 1]: 1 heisst „gerade eben", 0.5 nach einer Halbwertszeit. */
+export declare function recencyDecay(ageMs: number, halfLifeDays: number): number;
+/**
+ * Komplexitaets-Modifikator in [-1, 1]. Positiv, wenn der Treffer der
+ * angeforderten Richtung entspricht.
+ */
+export declare function complexityModifierRawValue(payload: CodeChunkPayloadV1, bias: ComplexityBias): number | null;
+/**
+ * Baut die vollstaendige Score-Zerlegung eines Kandidaten.
+ *
+ * `duplicatePenaltyRawValue` kommt aus der Diversifizierung (siehe
+ * `diversify.ts`) und ist bereits in [0, 1]; das Vorzeichen setzt diese
+ * Funktion, damit die Strafe an genau EINER Stelle negativ wird.
+ */
+export declare function assembleScoreBreakdown(candidate: SearchCandidate, fusion: FusionResult, context: ScoringContext, duplicatePenaltyRawValue?: number): ScoreBreakdownV1;
+interface ClampResult {
+    boosts: ScoreComponentV1[];
+    clamped: boolean;
+    reason?: string;
+}
+/** Setzt {@link MAX_BOOST_SHARE} durch (siehe Modulkommentar). */
+export declare function clampBoosts(base: ScoreComponentV1, boosts: readonly ScoreComponentV1[]): ClampResult;
+export {};
+//# sourceMappingURL=scoring.d.ts.map

package/dist/scoring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoring.d.ts","sourceRoot":"","sources":["../src/scoring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGpG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,KAAK,CAAC;AAEjD,2EAA2E;AAC3E,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,8EAA8E;AAC9E,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,YAAY,CAAC;IACtB,cAAc,EAAE,cAAc,CAAC;IAC/B,wEAAwE;IACxE,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjD,sEAAsE;IACtE,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AA2BD,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CASxE;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,kBAAkB,EAC3B,IAAI,EAAE,cAAc,GACnB,MAAM,GAAG,IAAI,CAUf;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,eAAe,EAC1B,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,cAAc,EACvB,wBAAwB,SAAI,GAC3B,gBAAgB,CAkHlB;AAoBD,UAAU,WAAW;IACnB,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,kEAAkE;AAClE,wBAAgB,WAAW,CACzB,IAAI,EAAE,gBAAgB,EACtB,MAAM,EAAE,SAAS,gBAAgB,EAAE,GAClC,WAAW,CAoBb"}

package/dist/scoring.js

@@ -0,0 +1,175 @@
+import { RANKER_VERSION } from "@untangle-code/domain";
+import { readRawNumber } from "./payload.js";
+import { matchSymbolName } from "./symbol-match.js";
+/**
+ * Hoechster zulaessiger Anteil aller Boosts/Strafen am Basisscore.
+ *
+ * 0.5 heisst: die Heuristik darf einen Treffer um hoechstens die Haelfte
+ * seines Basisscores verschieben. Damit bleibt der Basisanteil (`baseShare`
+ * aus `validateScoreBreakdown`) immer bei mindestens 1/1.5 ≈ 0.667 — der
+ * Basiszweig behaelt also strukturell die Mehrheit. Der Wert ist eine
+ * Politik-Entscheidung dieses Pakets und hier bewusst als benannte Konstante
+ * sichtbar statt als Zahl im Code verstreut.
+ */
+export const MAX_BOOST_SHARE = 0.5;
+/**
+ * Referenzwert der kognitiven Komplexitaet fuer den Komplexitaets-Modifikator.
+ * 25 ist der Punkt, ab dem der Modifikator seinen vollen Ausschlag erreicht;
+ * er ist eine Skalierungsgroesse fuer die Rangfolge und ausdruecklich KEINE
+ * Qualitaetsschwelle (Schwellen gehoeren in die Quality Gate, spec.md §18).
+ */
+export const COMPLEXITY_REFERENCE_COGNITIVE = 25;
+/** Gewicht des Komplexitaets-Modifikators, wenn die Anfrage ihn anfordert. */
+export const COMPLEXITY_MODIFIER_WEIGHT = 0.1;
+function pathBoost(payload, queryText) {
+    const query = queryText.trim();
+    if (query === "") {
+        return null;
+    }
+    const path = payload.file_path;
+    const segments = path.split("/");
+    if (path === query) {
+        return raw("exact_path_boost", 1, `file_path == "${path}"`);
+    }
+    if (segments.includes(query)) {
+        return raw("exact_path_boost", 0.75, `path segment == "${query}"`);
+    }
+    if (path.includes(query)) {
+        return raw("exact_path_boost", 0.5, `file_path contains "${query}"`);
+    }
+    return null;
+}
+function raw(kind, rawValue, evidence) {
+    // `weight` wird erst in `assembleScoreBreakdown` gesetzt; hier steht das
+    // rohe Signal mit seinem Beleg.
+    return { kind, rawValue, weight: 0, contribution: 0, evidence };
+}
+/** Zeitzerfall in [0, 1]: 1 heisst „gerade eben", 0.5 nach einer Halbwertszeit. */
+export function recencyDecay(ageMs, halfLifeDays) {
+    if (ageMs <= 0) {
+        return 1;
+    }
+    const halfLifeMs = halfLifeDays * 24 * 60 * 60 * 1000;
+    if (halfLifeMs <= 0) {
+        return 0;
+    }
+    return Math.pow(0.5, ageMs / halfLifeMs);
+}
+/**
+ * Komplexitaets-Modifikator in [-1, 1]. Positiv, wenn der Treffer der
+ * angeforderten Richtung entspricht.
+ */
+export function complexityModifierRawValue(payload, bias) {
+    if (bias === "none") {
+        return null;
+    }
+    const cognitive = payload.cognitive;
+    if (cognitive === undefined) {
+        return null;
+    }
+    const normalized = Math.min(cognitive / COMPLEXITY_REFERENCE_COGNITIVE, 1);
+    return bias === "prefer-simple" ? 1 - 2 * normalized : 2 * normalized - 1;
+}
+/**
+ * Baut die vollstaendige Score-Zerlegung eines Kandidaten.
+ *
+ * `duplicatePenaltyRawValue` kommt aus der Diversifizierung (siehe
+ * `diversify.ts`) und ist bereits in [0, 1]; das Vorzeichen setzt diese
+ * Funktion, damit die Strafe an genau EINER Stelle negativ wird.
+ */
+export function assembleScoreBreakdown(candidate, fusion, context, duplicatePenaltyRawValue = 0) {
+    const { payload } = candidate;
+    const base = {
+        kind: "base_hybrid",
+        rawValue: fusion.normalized,
+        weight: 1,
+        contribution: fusion.normalized,
+        evidence: describeBranches(fusion),
+    };
+    const boosts = [];
+    const symbolMatch = matchSymbolName(payload, context.queryText);
+    if (symbolMatch !== null) {
+        boosts.push(withWeight(raw("exact_symbol_boost", symbolMatch.strength, symbolMatch.evidence), context.weights.exactSymbol));
+    }
+    const pathComponent = pathBoost(payload, context.queryText);
+    if (pathComponent !== null) {
+        boosts.push(withWeight(pathComponent, context.weights.exactPath));
+    }
+    const priority = context.repoPriorities[payload.repo_id];
+    if (priority !== undefined && priority !== 0) {
+        boosts.push(withWeight(raw("repo_priority_boost", priority, `configured priority of repo "${payload.repo_id}"`), context.weights.repoPriority));
+    }
+    const proximity = payload.symbol_id === undefined ? undefined : context.graphProximity.get(payload.symbol_id);
+    if (proximity !== undefined && proximity !== 0) {
+        boosts.push(withWeight(raw("graph_proximity_boost", proximity, `graph proximity of symbol "${payload.symbol_id ?? ""}"`), context.weights.graphProximity));
+    }
+    const changedAt = readRawNumber(candidate.raw, "changed_at_epoch_ms");
+    if (changedAt !== undefined && context.nowEpochMs !== undefined) {
+        const decay = recencyDecay(context.nowEpochMs - changedAt, context.recencyHalfLifeDays);
+        if (decay > 0) {
+            boosts.push(withWeight(raw("recency_boost", decay, `changed_at_epoch_ms = ${changedAt}`), context.weights.recency));
+        }
+    }
+    const complexityRaw = complexityModifierRawValue(payload, context.complexityBias);
+    if (complexityRaw !== null) {
+        boosts.push(withWeight(raw("complexity_modifier", complexityRaw, `cognitive = ${String(payload.cognitive)} (bias "${context.complexityBias}", reference ${COMPLEXITY_REFERENCE_COGNITIVE})`), COMPLEXITY_MODIFIER_WEIGHT));
+    }
+    if (duplicatePenaltyRawValue > 0) {
+        boosts.push(withWeight(raw("duplicate_penalty", duplicatePenaltyRawValue, `file "${payload.file_path}" is already represented higher in the ranking`), -context.weights.duplicatePenalty));
+    }
+    const clamp = clampBoosts(base, boosts);
+    const components = [base, ...clamp.boosts];
+    const final = components.reduce((sum, component) => sum + component.contribution, 0);
+    return {
+        schemaVersion: 1,
+        final,
+        components,
+        inputs: {
+            ...(candidate.denseScore === undefined ? {} : { dense: candidate.denseScore }),
+            ...(candidate.denseRank === undefined ? {} : { denseRank: candidate.denseRank }),
+            ...(candidate.lexicalRank === undefined
+                ? {}
+                : { sparseRank: candidate.lexicalRank, lexicalRank: candidate.lexicalRank }),
+            ...(candidate.lexicalScore === undefined ? {} : { lexicalScore: candidate.lexicalScore }),
+            ...(candidate.symbolRank === undefined ? {} : { symbolRank: candidate.symbolRank }),
+            rrf: fusion.rrf,
+        },
+        rankerVersion: RANKER_VERSION,
+        clamped: clamp.clamped,
+        ...(clamp.reason === undefined ? {} : { clampReason: clamp.reason }),
+    };
+}
+function withWeight(component, weight) {
+    return { ...component, weight, contribution: component.rawValue * weight };
+}
+function describeBranches(fusion) {
+    const parts = [];
+    for (const branch of ["dense", "lexical", "symbol"]) {
+        const rank = fusion.ranks[branch];
+        if (rank !== undefined) {
+            const weight = fusion.weights?.[branch];
+            parts.push(weight === undefined ? `${branch}#${rank}` : `${branch}#${rank} x weight ${weight}`);
+        }
+    }
+    return parts.length === 0 ? "no branch contributed" : `RRF over ${parts.join(", ")}`;
+}
+/** Setzt {@link MAX_BOOST_SHARE} durch (siehe Modulkommentar). */
+export function clampBoosts(base, boosts) {
+    const boostMagnitude = boosts.reduce((sum, component) => sum + Math.abs(component.contribution), 0);
+    const baseMagnitude = Math.abs(base.contribution);
+    const budget = baseMagnitude * MAX_BOOST_SHARE;
+    if (boostMagnitude <= budget || boostMagnitude === 0) {
+        return { boosts: [...boosts], clamped: false };
+    }
+    const factor = budget / boostMagnitude;
+    return {
+        boosts: boosts.map((component) => ({
+            ...component,
+            weight: component.weight * factor,
+            contribution: component.contribution * factor,
+        })),
+        clamped: true,
+        reason: `boost magnitude ${boostMagnitude.toFixed(6)} exceeded ${MAX_BOOST_SHARE} of the base score ${baseMagnitude.toFixed(6)}; all non-base weights scaled by ${factor.toFixed(6)} (spec.md §13.3)`,
+    };
+}
+//# sourceMappingURL=scoring.js.map

package/dist/scoring.js.map

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

package/dist/sort.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Sortierung der Trefferliste (Nutzerwunsch A4: „Sortierung").
+ *
+ * Jede Sortierung ist zweistufig: erst das gewaehlte Kriterium, dann — IMMER —
+ * der Dedupe-Schluessel nach Codepoints. Der zweite Schritt ist nicht Kosmetik:
+ * ohne ihn haengt die Reihenfolge gleichbewerteter Treffer an der
+ * Antwortreihenfolge des Speichers, und dieselbe Anfrage liefert auf zwei
+ * Maschinen zwei Listen. `String#localeCompare` kommt dabei nie zum Einsatz
+ * (docs/BUILD_PLAN.md §3).
+ *
+ * Treffer ohne den jeweiligen Wert (keine Komplexitaet gemessen, keine
+ * Findability berechnet) landen ans ENDE der Liste, nicht an den Anfang: ein
+ * fehlender Wert ist kein Bestwert.
+ */
+import type { SearchHitV1 } from "@untangle-code/domain";
+import type { SearchSort } from "./types.js";
+/** Sortiert eine Kopie der Treffer nach dem gewaehlten Kriterium. */
+export declare function sortHits(hits: readonly SearchHitV1[], sort: SearchSort): SearchHitV1[];
+/** Weist die 1-basierten Raenge INNERHALB einer Profilgruppe zu. */
+export declare function assignRanks(hits: readonly SearchHitV1[]): SearchHitV1[];
+//# sourceMappingURL=sort.d.ts.map

package/dist/sort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sort.d.ts","sourceRoot":"","sources":["../src/sort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAuB7C,qEAAqE;AACrE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,EAAE,IAAI,EAAE,UAAU,GAAG,WAAW,EAAE,CAuCtF;AAED,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,GAAG,WAAW,EAAE,CAEvE"}

package/dist/sort.js

@@ -0,0 +1,53 @@
+import { compareCodepoints } from "@untangle-code/domain";
+function tiebreak(a, b) {
+    return compareCodepoints(a.dedupeKey, b.dedupeKey);
+}
+function compareOptionalNumber(a, b, direction) {
+    if (a === undefined && b === undefined) {
+        return 0;
+    }
+    if (a === undefined) {
+        return 1;
+    }
+    if (b === undefined) {
+        return -1;
+    }
+    return direction === "asc" ? a - b : b - a;
+}
+/** Sortiert eine Kopie der Treffer nach dem gewaehlten Kriterium. */
+export function sortHits(hits, sort) {
+    const copy = [...hits];
+    switch (sort) {
+        case "relevance":
+            copy.sort((a, b) => a.score.final === b.score.final ? tiebreak(a, b) : b.score.final - a.score.final);
+            break;
+        case "path":
+            copy.sort((a, b) => compareCodepoints(a.repoId, b.repoId) ||
+                compareCodepoints(a.filePath, b.filePath) ||
+                (a.range.startLine !== b.range.startLine
+                    ? a.range.startLine - b.range.startLine
+                    : tiebreak(a, b)));
+            break;
+        case "complexity-desc":
+        case "complexity-asc": {
+            const direction = sort === "complexity-asc" ? "asc" : "desc";
+            copy.sort((a, b) => {
+                const result = compareOptionalNumber(a.complexity?.cognitive, b.complexity?.cognitive, direction);
+                return result === 0 ? tiebreak(a, b) : result;
+            });
+            break;
+        }
+        case "findability-asc":
+            copy.sort((a, b) => {
+                const result = compareOptionalNumber(a.findability?.score, b.findability?.score, "asc");
+                return result === 0 ? tiebreak(a, b) : result;
+            });
+            break;
+    }
+    return copy;
+}
+/** Weist die 1-basierten Raenge INNERHALB einer Profilgruppe zu. */
+export function assignRanks(hits) {
+    return hits.map((hit, index) => ({ ...hit, rank: index + 1 }));
+}
+//# sourceMappingURL=sort.js.map

package/dist/sort.js.map

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

package/dist/symbol-match.d.ts

@@ -0,0 +1,21 @@
+import type { CodeChunkPayloadV1 } from "@untangle-code/domain";
+/** Ergebnis eines Namensvergleichs. */
+export interface SymbolMatch {
+    strength: number;
+    /** Beleg fuer die Score-Zerlegung, z. B. `symbol_name == "charge"`. */
+    evidence: string;
+}
+/** Vergleicht den Suchtext mit den Namensfeldern eines Chunks. */
+export declare function matchSymbolName(payload: CodeChunkPayloadV1, queryText: string): SymbolMatch | null;
+/**
+ * Kandidatenwerte fuer den Speicher-Filter auf `symbol_name`.
+ *
+ * Der Payload-Filter des Speichers kann nur exakte Werte vergleichen. Deshalb
+ * werden hier deterministisch die Schreibweisen erzeugt, die derselbe Name
+ * ueblicherweise hat: der Suchtext selbst, sein letztes Pfad-/FQN-Glied und —
+ * falls der Suchtext genau ein Wort ist — dieses Wort. Mehr NICHT: eine
+ * Kombinatorik ueber camelCase/snake_case-Varianten wuerde Treffer erfinden,
+ * die im Index gar nicht so heissen.
+ */
+export declare function symbolNameFilterCandidates(queryText: string): string[];
+//# sourceMappingURL=symbol-match.d.ts.map

package/dist/symbol-match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-match.d.ts","sourceRoot":"","sources":["../src/symbol-match.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAIhE,uCAAuC;AACvC,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,kEAAkE;AAClE,wBAAgB,eAAe,CAC7B,OAAO,EAAE,kBAAkB,EAC3B,SAAS,EAAE,MAAM,GAChB,WAAW,GAAG,IAAI,CA4BpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAWtE"}