@untangle-code/search 0.0.0-stage → 0.1.1

package/src/bm25.ts

@@ -0,0 +1,135 @@
+/**
+ * Deterministisches Okapi BM25 ueber den Kandidatenpool des Abrufkerns.
+ *
+ * WARUM EIGEN UND NICHT AUS DEM SPEICHER: Der `VectorStore` liefert im
+ * spaerlichen Zweig einen Rang, den der Speicher berechnet hat (bei Qdrant
+ * mit seiner eigenen IDF-Statistik ueber die ganze Collection). Dieser Rang
+ * ist ausgezeichnet fuer den ABRUF (Recall), aber er ist nicht in diesem
+ * Prozess nachrechenbar und aendert sich mit dem Speicherstand. Die
+ * Score-Zerlegung soll erklaeren, WARUM ein Treffer rankt — dafuer muss der
+ * lexikalische Anteil hier berechenbar sein. Deshalb:
+ *
+ * - der Speicher liefert KANDIDATEN (dichter und spaerlicher Zweig),
+ * - der lexikalische RANG entsteht in diesem Modul, mit den Statistiken des
+ *   Kandidatenpools.
+ *
+ * Der Preis dieser Entscheidung ist benannt und nicht wegdiskutiert: IDF
+ * ueber den Kandidatenpool ist nicht IDF ueber das ganze Korpus. Bei kleinen
+ * Pools kann ein Wort dadurch seltener aussehen, als es ist. Der Pool ist
+ * `candidateLimit` gross (Default 50, Maximum 200) und damit gross genug fuer
+ * eine stabile Ordnung INNERHALB des Pools — und nur diese Ordnung geht in
+ * die Fusion ein, nicht der absolute Wert. Siehe README „Bekannte Grenzen".
+ *
+ * Konstanten: k1 = 1.2, b = 0.75 — die Standardwerte aus Robertson/Sparck
+ * Jones. Sie sind hier keine „magischen Gewichte", sondern die dokumentierte
+ * Voreinstellung des Verfahrens; abweichende Werte muessten begruendet werden.
+ */
+import { compareCodepoints } from "@untangle-code/domain";
+
+import { informativeQueryTokens, termFrequencies, tokenizeIdentifiers } from "./tokenize.js";
+
+/** Saettigungskonstante der Termhaeufigkeit (Standardwert). */
+export const BM25_K1 = 1.2;
+/** Laengennormalisierung (Standardwert). */
+export const BM25_B = 0.75;
+
+/** Ein Dokument des lexikalischen Index. */
+export interface LexicalDocument {
+  id: string;
+  text: string;
+}
+
+/** Ein Rangeintrag des lexikalischen Zweigs. */
+export interface LexicalRanking {
+  id: string;
+  score: number;
+  /** 1-basierter Rang. */
+  rank: number;
+}
+
+interface PreparedDocument {
+  id: string;
+  frequencies: Map<string, number>;
+  length: number;
+}
+
+/**
+ * BM25 ueber eine feste Dokumentmenge. Die Statistiken werden EINMAL im
+ * Konstruktor gebildet; danach ist `score()` eine reine Funktion.
+ */
+export class Bm25Ranker {
+  private readonly documents: PreparedDocument[] = [];
+  private readonly documentFrequency = new Map<string, number>();
+  private readonly averageLength: number;
+
+  public constructor(
+    documents: readonly LexicalDocument[],
+    private readonly k1: number = BM25_K1,
+    private readonly b: number = BM25_B,
+  ) {
+    let totalLength = 0;
+    for (const document of documents) {
+      const tokens = tokenizeIdentifiers(document.text);
+      const frequencies = termFrequencies(tokens);
+      this.documents.push({ id: document.id, frequencies, length: tokens.length });
+      totalLength += tokens.length;
+      for (const term of frequencies.keys()) {
+        this.documentFrequency.set(term, (this.documentFrequency.get(term) ?? 0) + 1);
+      }
+    }
+    this.averageLength = this.documents.length === 0 ? 1 : totalLength / this.documents.length;
+  }
+
+  public get documentCount(): number {
+    return this.documents.length;
+  }
+
+  /**
+   * Inverse Dokumenthaeufigkeit in der geglaetteten Form
+   * `ln(1 + (N - df + 0.5) / (df + 0.5))` — immer positiv, damit ein in jedem
+   * Dokument vorkommender Term den Score nicht negativ macht.
+   */
+  private inverseDocumentFrequency(term: string): number {
+    const df = this.documentFrequency.get(term) ?? 0;
+    const n = this.documents.length;
+    return Math.log(1 + (n - df + 0.5) / (df + 0.5));
+  }
+
+  private scoreDocument(queryTerms: readonly string[], document: PreparedDocument): number {
+    let total = 0;
+    for (const term of queryTerms) {
+      const tf = document.frequencies.get(term) ?? 0;
+      if (tf === 0) {
+        continue;
+      }
+      const numerator = tf * (this.k1 + 1);
+      const denominator =
+        tf + this.k1 * (1 - this.b + this.b * (document.length / this.averageLength));
+      total += this.inverseDocumentFrequency(term) * (numerator / denominator);
+    }
+    return total;
+  }
+
+  /**
+   * Rangliste zu einem Suchtext. Dokumente mit Score 0 (kein Term getroffen)
+   * fallen heraus — sie haben lexikalisch nichts beigetragen und duerfen die
+   * Fusion nicht mit einem Scheinrang beeinflussen.
+   *
+   * Gleichstand wird deterministisch nach Codepoints der ID aufgeloest, nie
+   * nach Einfuegereihenfolge und nie ueber `localeCompare`.
+   */
+  public rank(queryText: string): LexicalRanking[] {
+    const queryTerms = [...termFrequencies(informativeQueryTokens(queryText)).keys()];
+    const scored: { id: string; score: number }[] = [];
+    for (const document of this.documents) {
+      const score = this.scoreDocument(queryTerms, document);
+      if (score > 0) {
+        scored.push({ id: document.id, score });
+      }
+    }
+    scored.sort((a, b) =>
+      a.score === b.score ? compareCodepoints(a.id, b.id) : b.score - a.score,
+    );
+    return scored.map((entry, index) => ({ id: entry.id, score: entry.score, rank: index + 1 }));
+  }
+}

package/src/deadline.ts

@@ -0,0 +1,59 @@
+import { UntangleError, type PortCallOptions } from "@untangle-code/domain";
+
+/** Bound hybrid branches and propagate outer cancellation even if an adapter hangs. */
+export async function withSearchBranchDeadline<T>(
+  branch: "dense" | "sparse" | "symbol",
+  timeoutMs: number | undefined,
+  retrieve: (options: PortCallOptions) => Promise<T>,
+  options?: PortCallOptions,
+  storeFailureCode: "QDRANT_UNAVAILABLE" | "LANCEDB_UNAVAILABLE" = "QDRANT_UNAVAILABLE",
+): Promise<T> {
+  options?.signal?.throwIfAborted();
+  const controller = new AbortController();
+  let timeoutError: UntangleError | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let onAbort: (() => void) | undefined;
+  const interrupted = new Promise<never>((_, reject) => {
+    onAbort = () => {
+      const reason: unknown = options?.signal?.reason;
+      reject(reason);
+      controller.abort(reason);
+    };
+    options?.signal?.addEventListener("abort", onAbort, { once: true });
+    if (timeoutMs !== undefined) {
+      timer = setTimeout(() => {
+        timeoutError = new UntangleError(
+          branch === "dense" ? "EMBEDDING_UNAVAILABLE" : storeFailureCode,
+          `retrieval branch "${branch}" exceeded its ${String(timeoutMs)}ms deadline`,
+          {
+            operation: "search_branch",
+            retryable: true,
+            context: { branch, timeoutMs, timedOut: true },
+          },
+        );
+        // Reject before notifying the adapter: an adapter's JOB_CANCELLED is
+        // caused by this local deadline and must not cancel successful peers.
+        reject(timeoutError);
+        controller.abort(timeoutError);
+      }, timeoutMs);
+    }
+  });
+  try {
+    // Promise.race installs handlers on both promises, including a late
+    // adapter rejection after a deadline. It cannot become unhandled.
+    return await Promise.race([
+      Promise.resolve().then(() => {
+        controller.signal.throwIfAborted();
+        return retrieve({ ...options, signal: controller.signal });
+      }),
+      interrupted,
+    ]);
+  } catch (error) {
+    options?.signal?.throwIfAborted();
+    if (timeoutError !== undefined) throw timeoutError;
+    throw error;
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    if (onAbort !== undefined) options?.signal?.removeEventListener("abort", onAbort);
+  }
+}

package/src/dedupe.ts

@@ -0,0 +1,99 @@
+/**
+ * Deduplizierung (spec.md §13.5, architecture.md §18.4).
+ *
+ * Mehrere Fragmente desselben Symbols duerfen nicht alle Top-Plaetze belegen.
+ * Der Dedupe-Schluessel ist woertlich der aus architecture.md §18.4:
+ *
+ *     workspace_id + repo_id + ref_id + metrics_scope_id
+ *
+ * Der Ref gehoert bewusst hinein: derselbe Code in zwei Branches oder zwei
+ * Worktrees sind ZWEI Antworten, nicht eine — wer ueber mehrere Refs sucht,
+ * will beide sehen, jeweils mit ihrer Herkunft (vision.md §1a „Branch- und
+ * Worktree-Bewusstsein").
+ *
+ * Verbunden werden die Bestandteile mit `ID_COMPONENT_SEPARATOR` (U+001F),
+ * derselben Trennzeichenkonvention wie bei allen Untangle-IDs — ein Pfad oder
+ * Name kann so keinen Schluessel „ueberlaufen" lassen.
+ */
+import type { CodeChunkPayloadV1, RelatedFragmentV1 } from "@untangle-code/domain";
+import { ID_COMPONENT_SEPARATOR, compareCodepoints } from "@untangle-code/domain";
+
+import type { SearchCandidate } from "./payload.js";
+
+/** Baut den Dedupe-Schluessel eines Chunk-Payloads. */
+export function buildDedupeKey(payload: CodeChunkPayloadV1): string {
+  return [payload.workspace_id, payload.repo_id, payload.ref_id, payload.metrics_scope_id].join(
+    ID_COMPONENT_SEPARATOR,
+  );
+}
+
+/** Ein Kandidat mit seinem Basisscore, wie ihn die Fusion geliefert hat. */
+export interface ScoredCandidate {
+  candidate: SearchCandidate;
+  /** Normalisierter Basisscore aus der Fusion, in [0, 1]. */
+  baseScore: number;
+}
+
+/** Ergebnis der Deduplizierung einer Gruppe. */
+export interface DedupedCandidate {
+  primary: ScoredCandidate;
+  dedupeKey: string;
+  relatedFragments: RelatedFragmentV1[];
+  /** Die verdraengten Kandidaten — fuer den Skip-Ledger (E4). */
+  absorbed: ScoredCandidate[];
+}
+
+/**
+ * Fasst Kandidaten mit gleichem Dedupe-Schluessel zusammen.
+ *
+ * Primaer bleibt der bestbewertete; bei Gleichstand entscheidet die
+ * Codepoint-Ordnung der Chunk-ID — nie die Reihenfolge, in der der Speicher
+ * geantwortet hat.
+ *
+ * Die Eingabereihenfolge bleibt fuer die Ausgabe massgeblich: die Gruppen
+ * erscheinen in der Reihenfolge ihres ersten Vorkommens, damit die Rangfolge
+ * der Fusion erhalten bleibt.
+ */
+export function dedupeCandidates(scored: readonly ScoredCandidate[]): DedupedCandidate[] {
+  const groups = new Map<string, ScoredCandidate[]>();
+  for (const entry of scored) {
+    const key = buildDedupeKey(entry.candidate.payload);
+    const existing = groups.get(key);
+    if (existing === undefined) {
+      groups.set(key, [entry]);
+    } else {
+      existing.push(entry);
+    }
+  }
+
+  return [...groups].map(([key, group]) => {
+    const members = [...group].sort(compareScored);
+    const primary = members[0] as ScoredCandidate;
+    const absorbed = members.slice(1);
+    return {
+      primary,
+      dedupeKey: key,
+      absorbed,
+      relatedFragments: absorbed.map((member) => toRelatedFragment(member)),
+    };
+  });
+}
+
+function compareScored(a: ScoredCandidate, b: ScoredCandidate): number {
+  if (a.baseScore !== b.baseScore) {
+    return b.baseScore - a.baseScore;
+  }
+  return compareCodepoints(a.candidate.payload.chunk_id, b.candidate.payload.chunk_id);
+}
+
+function toRelatedFragment(entry: ScoredCandidate): RelatedFragmentV1 {
+  const { payload } = entry.candidate;
+  return {
+    chunkId: payload.chunk_id,
+    chunkKind: payload.chunk_kind,
+    ...(payload.fragment_index === undefined ? {} : { fragmentIndex: payload.fragment_index }),
+    startLine: payload.start_line,
+    endLine: payload.end_line,
+    score: entry.baseScore,
+  };
+}

package/src/diversify.ts

@@ -0,0 +1,71 @@
+/**
+ * Diversifizierung (spec.md §13.2 Schritt 10, architecture.md §18.5).
+ *
+ * Ziel ist der Fall „zehn nahezu identische Treffer derselben Datei". Nach der
+ * Deduplizierung ueber `metrics_scope_id` bleiben immer noch mehrere Symbole
+ * derselben Datei uebrig — und wer nach „Funktion X" sucht, will nicht
+ * zehnmal dieselbe Datei sehen, sondern die zehn besten STELLEN.
+ *
+ * Verfahren (bewusst ohne Inhaltsvektoren): Die Liste wird in Rangfolge
+ * durchlaufen; jeder Treffer bekommt eine Strafe, die davon abhaengt, wie oft
+ * seine Datei (und, schwaecher, sein Repository) vorher schon vertreten war:
+ *
+ *     strafe(n) = 1 - 1 / (1 + n)
+ *
+ * mit `n` = Zahl der vorher schon vertretenen Treffer derselben Datei. Der
+ * erste Treffer einer Datei bekommt also 0, der zweite 0.5, der dritte 0.667 —
+ * eine saettigende Kurve, die nie 1 erreicht. Damit verschwindet keine Datei
+ * vollstaendig aus dem Ergebnis; sie wird nur immer teurer.
+ *
+ * Warum keine Content-MMR: dafuer braeuchte es die dichten Vektoren aller
+ * Kandidaten. Der `VectorStore`-Port liefert sie beim Suchen nicht mit
+ * (`hybridQuery` gibt Payload, keine Vektoren), und sie nachzuladen kostet
+ * eine zweite Runde ueber den Speicher. Die datei-/repo-basierte Streuung ist
+ * die Dimension, die architecture.md §18.5 zuerst nennt, und sie kostet nichts.
+ * Der Verzicht auf die Content-Dimension steht in der README unter „Bekannte
+ * Grenzen".
+ */
+import type { CodeChunkPayloadV1 } from "@untangle-code/domain";
+import { ID_COMPONENT_SEPARATOR } from "@untangle-code/domain";
+
+/** Anteil der Datei-Strafe, den ein reiner Repo-Wiederholer bekommt. */
+export const REPO_REPETITION_SHARE = 0.25;
+
+/** Ein Eintrag der Diversifizierung: Gegenstand plus zugeteilte Strafe. */
+export interface DiversificationEntry<T> {
+  item: T;
+  /** Rohwert der `duplicate_penalty` in [0, 1). */
+  penaltyRawValue: number;
+}
+
+function saturatingPenalty(previousOccurrences: number): number {
+  return 1 - 1 / (1 + previousOccurrences);
+}
+
+/**
+ * Berechnet die Duplikatsstrafen in Rangfolge.
+ *
+ * Die Funktion sortiert NICHT um — sie bewertet nur. Die Neuordnung passiert
+ * spaeter ueber den fertigen Endscore, damit jede Verschiebung in der
+ * Score-Zerlegung sichtbar ist statt in einem unsichtbaren Sortierschritt.
+ */
+export function assignDuplicatePenalties<T>(
+  items: readonly T[],
+  payloadOf: (item: T) => CodeChunkPayloadV1,
+): DiversificationEntry<T>[] {
+  const fileCounts = new Map<string, number>();
+  const repoCounts = new Map<string, number>();
+  return items.map((item) => {
+    const payload = payloadOf(item);
+    const repoKey = [payload.repo_id, payload.ref_id].join(ID_COMPONENT_SEPARATOR);
+    const fileKey = [repoKey, payload.file_id].join(ID_COMPONENT_SEPARATOR);
+    const previousFile = fileCounts.get(fileKey) ?? 0;
+    const previousRepo = repoCounts.get(repoKey) ?? 0;
+    fileCounts.set(fileKey, previousFile + 1);
+    repoCounts.set(repoKey, previousRepo + 1);
+    const filePenalty = saturatingPenalty(previousFile);
+    const repoPenalty =
+      previousFile === 0 ? saturatingPenalty(previousRepo) * REPO_REPETITION_SHARE : 0;
+    return { item, penaltyRawValue: Math.min(1, filePenalty + repoPenalty) };
+  });
+}