@untangle-code/search 0.0.0-stage → 0.1.0

package/src/retrieval.ts

@@ -0,0 +1,299 @@
+/** Independent recall branches, bounded provider calls and deterministic failure diagnostics. */
+import {
+  UntangleError,
+  compareCodepoints,
+  isUntangleError,
+  type ErrorCode,
+  type PayloadFilter,
+  type PortCallOptions,
+  type ScoredPointV1,
+  type ScrollPageV1,
+  type ToolWarningV1,
+  type VectorStore,
+} from "@untangle-code/domain";
+
+import { withSearchBranchDeadline } from "./deadline.js";
+import { buildSymbolNameFilter } from "./filter.js";
+import type { SearchSkipInput } from "./ledger.js";
+import type { ProfileTargetV1, SparseVectorizer } from "./port.js";
+import { symbolNameFilterCandidates } from "./symbol-match.js";
+import type { SearchMode } from "./types.js";
+
+export type RetrievalBranch = "dense" | "sparse" | "symbol";
+type RetrievalTarget = Pick<ProfileTargetV1, "collection" | "embeddingProfileId" | "embedder">;
+
+export interface IndependentRetrievalRequest {
+  vectorStore: Pick<VectorStore, "hybridQuery" | "scroll" | "backend">;
+  target: RetrievalTarget;
+  text: string;
+  filter: PayloadFilter;
+  candidateLimit: number;
+  mode: SearchMode;
+  sparseVectorizer?: SparseVectorizer;
+  branchTimeoutMs: number;
+}
+
+interface FailedBranch {
+  branch: RetrievalBranch;
+  status: "failed";
+  error: unknown;
+}
+
+type BranchOutcome<T> =
+  | FailedBranch
+  | { branch: RetrievalBranch; status: "not_requested" }
+  | { branch: RetrievalBranch; status: "succeeded"; result: T };
+
+export interface IndependentRetrievalResult {
+  densePoints: readonly ScoredPointV1[];
+  sparsePoints: readonly ScoredPointV1[];
+  symbolPage?: ScrollPageV1;
+  completedBranches: ReadonlySet<RetrievalBranch>;
+  failures: readonly FailedBranch[];
+  warnings: ToolWarningV1[];
+  caveats: string[];
+  skipped: SearchSkipInput[];
+}
+
+/** The mode controls both recall and ranking, so it has one shared definition. */
+export function branchesOfMode(mode: SearchMode): {
+  dense: boolean;
+  lexical: boolean;
+  symbol: boolean;
+} {
+  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: unknown, options?: PortCallOptions): void {
+  options?.signal?.throwIfAborted();
+  if (
+    (isUntangleError(error) && error.code === "JOB_CANCELLED") ||
+    (error instanceof Error && error.name === "AbortError")
+  ) {
+    throw error;
+  }
+}
+
+async function retrieveDense(
+  request: IndependentRetrievalRequest,
+  options: PortCallOptions,
+): Promise<ScoredPointV1[]> {
+  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: IndependentRetrievalRequest,
+  options: PortCallOptions,
+): Promise<ScoredPointV1[]> {
+  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: IndependentRetrievalRequest,
+  options: PortCallOptions,
+): Promise<ScrollPageV1> {
+  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<T>(
+  branch: RetrievalBranch,
+  enabled: boolean,
+  request: IndependentRetrievalRequest,
+  retrieve: (request: IndependentRetrievalRequest, options: PortCallOptions) => Promise<T>,
+  options: PortCallOptions,
+): Promise<BranchOutcome<T>> {
+  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<T>(outcome: BranchOutcome<T>): T | undefined {
+  return outcome.status === "succeeded" ? outcome.result : undefined;
+}
+
+function isFailedBranch(outcome: BranchOutcome<unknown>): outcome is FailedBranch {
+  return outcome.status === "failed";
+}
+
+function branchFailureCode(failure: FailedBranch | undefined): ErrorCode {
+  if (failure !== undefined && isUntangleError(failure.error)) return failure.error.code;
+  return failure?.branch === "dense" ? "EMBEDDING_UNAVAILABLE" : "QDRANT_UNAVAILABLE";
+}
+
+function timeoutDetails(error: unknown): Record<string, unknown> {
+  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: RetrievalTarget,
+  failures: readonly FailedBranch[],
+): Pick<IndependentRetrievalResult, "warnings" | "caveats" | "skipped"> {
+  const warnings: ToolWarningV1[] = [];
+  const caveats: string[] = [];
+  const skipped: SearchSkipInput[] = [];
+  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: IndependentRetrievalRequest,
+  options?: PortCallOptions,
+): Promise<IndependentRetrievalResult> {
+  options?.signal?.throwIfAborted();
+  const active = branchesOfMode(request.mode);
+  const controller = new AbortController();
+  const linkedOptions: PortCallOptions = {
+    ...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: IndependentRetrievalResult,
+  target: RetrievalTarget,
+): void {
+  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,
+    },
+  );
+}

package/src/scoring.ts

@@ -0,0 +1,321 @@
+/**
+ * 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 { RANKER_VERSION } from "@untangle-code/domain";
+
+import type { FusionResult } from "./fusion.js";
+import type { SearchCandidate } from "./payload.js";
+import { readRawNumber } from "./payload.js";
+import { matchSymbolName } from "./symbol-match.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 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;
+
+/** 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 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;
+}
+
+function pathBoost(payload: CodeChunkPayloadV1, queryText: string): ScoreComponentV1 | null {
+  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: ScoreComponentV1["kind"], rawValue: number, evidence: string): ScoreComponentV1 {
+  // `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: number, halfLifeDays: number): number {
+  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: CodeChunkPayloadV1,
+  bias: ComplexityBias,
+): number | null {
+  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: SearchCandidate,
+  fusion: FusionResult,
+  context: ScoringContext,
+  duplicatePenaltyRawValue = 0,
+): ScoreBreakdownV1 {
+  const { payload } = candidate;
+  const base: ScoreComponentV1 = {
+    kind: "base_hybrid",
+    rawValue: fusion.normalized,
+    weight: 1,
+    contribution: fusion.normalized,
+    evidence: describeBranches(fusion),
+  };
+
+  const boosts: ScoreComponentV1[] = [];
+
+  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: ScoreComponentV1, weight: number): ScoreComponentV1 {
+  return { ...component, weight, contribution: component.rawValue * weight };
+}
+
+function describeBranches(fusion: FusionResult): string {
+  const parts: string[] = [];
+  for (const branch of ["dense", "lexical", "symbol"] as const) {
+    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(", ")}`;
+}
+
+interface ClampResult {
+  boosts: ScoreComponentV1[];
+  clamped: boolean;
+  reason?: string;
+}
+
+/** Setzt {@link MAX_BOOST_SHARE} durch (siehe Modulkommentar). */
+export function clampBoosts(
+  base: ScoreComponentV1,
+  boosts: readonly ScoreComponentV1[],
+): ClampResult {
+  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)`,
+  };
+}

package/src/sort.ts

@@ -0,0 +1,86 @@
+/**
+ * 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 { compareCodepoints } from "@untangle-code/domain";
+
+import type { SearchSort } from "./types.js";
+
+function tiebreak(a: SearchHitV1, b: SearchHitV1): number {
+  return compareCodepoints(a.dedupeKey, b.dedupeKey);
+}
+
+function compareOptionalNumber(
+  a: number | undefined,
+  b: number | undefined,
+  direction: "asc" | "desc",
+): number {
+  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: readonly SearchHitV1[], sort: SearchSort): SearchHitV1[] {
+  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: readonly SearchHitV1[]): SearchHitV1[] {
+  return hits.map((hit, index) => ({ ...hit, rank: index + 1 }));
+}