@untangle-code/search 0.0.0-stage → 0.1.1

package/dist/symbol-match.js

@@ -0,0 +1,72 @@
+/**
+ * Exakte und nahe Symbolnamen-Treffer (dritter Abrufzweig).
+ *
+ * Der Nutzerfall aus vision.md §1d ist woertlich: „wenn ich nach ‚Funktion X'
+ * suche". Ein dichter Vektor kann einen exakten Namen verfehlen, weil er
+ * Bedeutung und nicht Zeichen vergleicht; BM25 kann ihn unter langen Rumpf-
+ * texten begraben. Der Symbolzweig ist deshalb kein Bonus auf einen anderen
+ * Zweig, sondern eine eigene Rangliste mit eigener Begruendung.
+ *
+ * Vier Stufen, absichtlich grob und vollstaendig dokumentiert (jede feinere
+ * Abstufung waere ein magisches Gewicht ohne Beleg):
+ *
+ * | Staerke | Bedingung |
+ * |---|---|
+ * | 1.00 | `symbol_name` ist zeichengleich mit dem Suchtext |
+ * | 0.80 | zeichengleich bis auf Gross-/Kleinschreibung |
+ * | 0.60 | `symbol_fqn` endet auf den Suchtext (`Service.charge`) |
+ * | 0.40 | alle Teilwoerter der Anfrage stecken im Namen (`getUser` ⊂ `getUserById`) |
+ */
+import { compareCodepoints } from "@untangle-code/domain";
+import { identifierParts } from "./tokenize.js";
+/** Vergleicht den Suchtext mit den Namensfeldern eines Chunks. */
+export function matchSymbolName(payload, queryText) {
+    const name = payload.symbol_name;
+    const query = queryText.trim();
+    if (query === "") {
+        return null;
+    }
+    if (name !== undefined && name === query) {
+        return { strength: 1, evidence: `symbol_name == "${name}"` };
+    }
+    if (name !== undefined && name.toLowerCase() === query.toLowerCase()) {
+        return { strength: 0.8, evidence: `symbol_name ~= "${name}" (case-insensitive)` };
+    }
+    const fqn = payload.symbol_fqn;
+    if (fqn !== undefined &&
+        (fqn === query || fqn.endsWith(`.${query}`) || fqn.endsWith(`::${query}`))) {
+        return { strength: 0.6, evidence: `symbol_fqn "${fqn}" ends with "${query}"` };
+    }
+    if (name === undefined) {
+        return null;
+    }
+    const queryParts = identifierParts(query);
+    const nameParts = new Set(identifierParts(name));
+    if (queryParts.length > 0 && queryParts.every((part) => nameParts.has(part))) {
+        return { strength: 0.4, evidence: `symbol_name "${name}" contains all query parts` };
+    }
+    return 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 function symbolNameFilterCandidates(queryText) {
+    const query = queryText.trim();
+    if (query === "") {
+        return [];
+    }
+    const candidates = new Set([query]);
+    const lastSegment = query.split(/[.:#/]/u).at(-1);
+    if (lastSegment !== undefined && lastSegment !== "") {
+        candidates.add(lastSegment);
+    }
+    return [...candidates].sort(compareCodepoints);
+}
+//# sourceMappingURL=symbol-match.js.map

package/dist/symbol-match.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-match.js","sourceRoot":"","sources":["../src/symbol-match.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAG1D,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAShD,kEAAkE;AAClE,MAAM,UAAU,eAAe,CAC7B,OAA2B,EAC3B,SAAiB;IAEjB,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC;IACjC,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;IAC/B,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;QACjB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;QACzC,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,mBAAmB,IAAI,GAAG,EAAE,CAAC;IAC/D,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,WAAW,EAAE,KAAK,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;QACrE,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,mBAAmB,IAAI,sBAAsB,EAAE,CAAC;IACpF,CAAC;IACD,MAAM,GAAG,GAAG,OAAO,CAAC,UAAU,CAAC;IAC/B,IACE,GAAG,KAAK,SAAS;QACjB,CAAC,GAAG,KAAK,KAAK,IAAI,GAAG,CAAC,QAAQ,CAAC,IAAI,KAAK,EAAE,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC,EAC1E,CAAC;QACD,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,eAAe,GAAG,gBAAgB,KAAK,GAAG,EAAE,CAAC;IACjF,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,UAAU,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IAC1C,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;IACjD,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QAC7E,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,QAAQ,EAAE,gBAAgB,IAAI,4BAA4B,EAAE,CAAC;IACvF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,0BAA0B,CAAC,SAAiB;IAC1D,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;IAC/B,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;QACjB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,UAAU,GAAG,IAAI,GAAG,CAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IAC5C,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAClD,IAAI,WAAW,KAAK,SAAS,IAAI,WAAW,KAAK,EAAE,EAAE,CAAC;QACpD,UAAU,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,CAAC,GAAG,UAAU,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;AACjD,CAAC"}

package/dist/tokenize.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Bezeichner-bewusste Tokenisierung fuer den lexikalischen Zweig
+ * (spec.md §13.2 Schritt 3: „Query normalisieren, ohne Identifier-Zeichen zu
+ * zerstoeren").
+ *
+ * Eine reine Wortgrenzen-Tokenisierung („alles ausser Buchstaben/Ziffern ist
+ * Trenner") zerlegt `get_user_by_id` korrekt, `getUserById` aber ueberhaupt
+ * nicht — dabei ist genau das der Fall, den der Nutzer meint, wenn er nach
+ * „Funktion X" sucht. Diese Tokenisierung liefert deshalb ZWEI Ebenen:
+ *
+ * 1. den ganzen, kleingeschriebenen Bezeichner (`getuserbyid`) — damit ein
+ *    exakter Namenstreffer den hoechsten lexikalischen Gewinn hat;
+ * 2. seine Teilwoerter (`get`, `user`, `by`, `id`) — damit ein Treffer auch
+ *    ueber Teilbegriffe gefunden wird.
+ *
+ * Beide Ebenen landen im selben Token-Bag. Das ist bewusst: BM25 belohnt
+ * dadurch einen Volltreffer zusaetzlich zu seinen Teilen, ohne dass es dafuer
+ * ein Sonderregelwerk im Ranker braucht.
+ *
+ * Alles hier ist reine Arithmetik ueber den Eingabetext — kein Locale, keine
+ * Zeit, kein Zufall (docs/BUILD_PLAN.md §3 „Determinismus").
+ */
+export { identifierParts, splitIdentifierRun, tokenizeIdentifiers } from "@untangle-code/domain";
+/**
+ * Tokenisiert eine frei formulierte Anfrage fuer den lexikalischen Rang und
+ * entfernt nur grammatische Fragehuelsen. Wiederholungen bleiben erhalten;
+ * der Aufrufer entscheidet wie beim normalen Token-Bag selbst, ob er daraus
+ * eine Menge oder Haeufigkeiten braucht.
+ */
+export declare function informativeQueryTokens(text: string): string[];
+/**
+ * Erkennt die enge Form, fuer die der Benchmark einen systematischen
+ * Cross-Language-Konflikt belegt: eine deutsch formulierte Frage vor
+ * ueberwiegend englischen Codebezeichnern. Das ist bewusst KEINE allgemeine
+ * Spracherkennung. Eindeutige deutsche Fragewoerter reichen; das auch im
+ * Englischen vorkommende `was` braucht zwei weitere Grammatikmarker.
+ */
+export declare function isLikelyGermanQuestion(text: string): boolean;
+/** Token-Haeufigkeiten als Map; Reihenfolge der Einfuegung ist Textreihenfolge. */
+export declare function termFrequencies(tokens: readonly string[]): Map<string, number>;
+//# sourceMappingURL=tokenize.d.ts.map

package/dist/tokenize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenize.d.ts","sourceRoot":"","sources":["../src/tokenize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAiJjG;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAI7D;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAa5D;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAM9E"}

package/dist/tokenize.js

@@ -0,0 +1,202 @@
+/**
+ * Bezeichner-bewusste Tokenisierung fuer den lexikalischen Zweig
+ * (spec.md §13.2 Schritt 3: „Query normalisieren, ohne Identifier-Zeichen zu
+ * zerstoeren").
+ *
+ * Eine reine Wortgrenzen-Tokenisierung („alles ausser Buchstaben/Ziffern ist
+ * Trenner") zerlegt `get_user_by_id` korrekt, `getUserById` aber ueberhaupt
+ * nicht — dabei ist genau das der Fall, den der Nutzer meint, wenn er nach
+ * „Funktion X" sucht. Diese Tokenisierung liefert deshalb ZWEI Ebenen:
+ *
+ * 1. den ganzen, kleingeschriebenen Bezeichner (`getuserbyid`) — damit ein
+ *    exakter Namenstreffer den hoechsten lexikalischen Gewinn hat;
+ * 2. seine Teilwoerter (`get`, `user`, `by`, `id`) — damit ein Treffer auch
+ *    ueber Teilbegriffe gefunden wird.
+ *
+ * Beide Ebenen landen im selben Token-Bag. Das ist bewusst: BM25 belohnt
+ * dadurch einen Volltreffer zusaetzlich zu seinen Teilen, ohne dass es dafuer
+ * ein Sonderregelwerk im Ranker braucht.
+ *
+ * Alles hier ist reine Arithmetik ueber den Eingabetext — kein Locale, keine
+ * Zeit, kein Zufall (docs/BUILD_PLAN.md §3 „Determinismus").
+ */
+import { tokenizeIdentifiers } from "@untangle-code/domain";
+// Indexing, sparse queries and reranking must use one versioned token space.
+export { identifierParts, splitIdentifierRun, tokenizeIdentifiers } from "@untangle-code/domain";
+/**
+ * Funktionswoerter, die in frei formulierten Suchfragen fast nur die Form der
+ * Frage beschreiben. Sie als BM25-Begriffe zu werten bevorzugt lange Prosa,
+ * die ebenfalls oft "wo wird"/"how is" enthaelt, vor dem gesuchten Code.
+ *
+ * Die Liste ist absichtlich klein und enthaelt nur geschlossene grammatische
+ * Klassen in Deutsch und Englisch. Fachwoerter, Verben und Bezeichner werden
+ * nie als Stopwoerter geraten. Wenn eine Anfrage ausschliesslich daraus
+ * besteht, faellt {@link informativeQueryTokens} auf die Originaltokens
+ * zurueck, damit beispielsweise eine Symbolsuche nach `is` nicht verschwindet.
+ */
+const QUERY_STOP_WORDS = new Set([
+    "a",
+    "als",
+    "an",
+    "and",
+    "are",
+    "as",
+    "at",
+    "auf",
+    "aus",
+    "be",
+    "bei",
+    "by",
+    "das",
+    "dass",
+    "dem",
+    "den",
+    "der",
+    "des",
+    "die",
+    "does",
+    "ein",
+    "eine",
+    "einem",
+    "einen",
+    "einer",
+    "eines",
+    "es",
+    "for",
+    "from",
+    "für",
+    "fuer",
+    "how",
+    "im",
+    "in",
+    "into",
+    "is",
+    "ist",
+    "it",
+    "mit",
+    "of",
+    "on",
+    "or",
+    "sich",
+    "sind",
+    "that",
+    "the",
+    "this",
+    "to",
+    "und",
+    "von",
+    "was",
+    "wann",
+    "warum",
+    "werden",
+    "what",
+    "when",
+    "where",
+    "which",
+    "wie",
+    "wird",
+    "with",
+    "wo",
+    "wofür",
+    "wofuer",
+    "who",
+    "why",
+    "welche",
+    "welchem",
+    "welchen",
+    "welcher",
+    "welches",
+    "wer",
+    "zu",
+]);
+const UNAMBIGUOUS_GERMAN_QUESTION_OPENERS = new Set([
+    "warum",
+    "wann",
+    "welche",
+    "welchem",
+    "welchen",
+    "welcher",
+    "welches",
+    "wer",
+    "wie",
+    "wo",
+    "wofür",
+    "wofuer",
+]);
+const GERMAN_WAS_PREDICATES = new Set([
+    "bedeutet",
+    "geschieht",
+    "ist",
+    "passiert",
+    "sind",
+    "werden",
+    "wird",
+]);
+const GERMAN_INFLECTED_QUESTION_PRONOUNS = new Set([
+    "welche",
+    "welchem",
+    "welchen",
+    "welcher",
+    "welches",
+]);
+const GERMAN_GRAMMAR_MARKERS = new Set([
+    "das",
+    "dass",
+    "dem",
+    "den",
+    "der",
+    "des",
+    "die",
+    "ein",
+    "eine",
+    "einem",
+    "einen",
+    "einer",
+    "eines",
+    "ist",
+    "sich",
+    "und",
+    "von",
+    "werden",
+    "wird",
+    "zu",
+]);
+/**
+ * Tokenisiert eine frei formulierte Anfrage fuer den lexikalischen Rang und
+ * entfernt nur grammatische Fragehuelsen. Wiederholungen bleiben erhalten;
+ * der Aufrufer entscheidet wie beim normalen Token-Bag selbst, ob er daraus
+ * eine Menge oder Haeufigkeiten braucht.
+ */
+export function informativeQueryTokens(text) {
+    const tokens = tokenizeIdentifiers(text);
+    const informative = tokens.filter((token) => !QUERY_STOP_WORDS.has(token));
+    return informative.length === 0 ? tokens : informative;
+}
+/**
+ * Erkennt die enge Form, fuer die der Benchmark einen systematischen
+ * Cross-Language-Konflikt belegt: eine deutsch formulierte Frage vor
+ * ueberwiegend englischen Codebezeichnern. Das ist bewusst KEINE allgemeine
+ * Spracherkennung. Eindeutige deutsche Fragewoerter reichen; das auch im
+ * Englischen vorkommende `was` braucht zwei weitere Grammatikmarker.
+ */
+export function isLikelyGermanQuestion(text) {
+    const tokens = tokenizeIdentifiers(text);
+    const first = tokens[0];
+    if (first === undefined) {
+        return false;
+    }
+    return (UNAMBIGUOUS_GERMAN_QUESTION_OPENERS.has(first) ||
+        (first === "in" && GERMAN_INFLECTED_QUESTION_PRONOUNS.has(tokens[1] ?? "")) ||
+        (first === "was" &&
+            (GERMAN_WAS_PREDICATES.has(tokens[1] ?? "") ||
+                new Set(tokens.filter((token) => GERMAN_GRAMMAR_MARKERS.has(token))).size >= 2)));
+}
+/** Token-Haeufigkeiten als Map; Reihenfolge der Einfuegung ist Textreihenfolge. */
+export function termFrequencies(tokens) {
+    const counts = new Map();
+    for (const token of tokens) {
+        counts.set(token, (counts.get(token) ?? 0) + 1);
+    }
+    return counts;
+}
+//# sourceMappingURL=tokenize.js.map

package/dist/tokenize.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Paket-eigene Vertraege des Abrufkerns.
+ *
+ * Grundsatz: Alles, was schon in `@untangle-code/domain` steht
+ * (`SearchRequestV1`, `SearchQueryV1`, `ScoreBreakdownV1`, `SearchHitV1`,
+ * `SearchResultSetV1`, `SkipLedgerEntryV1`, …), wird NICHT neu definiert,
+ * sondern verwendet. Hier stehen nur die Erweiterungen, die der Abrufkern
+ * zusaetzlich braucht und die die Werkzeuggrenze aus spec.md §13.1 bewusst
+ * nicht kennt:
+ *
+ * - Suchmodus (semantisch / lexikalisch / Symbolname / hybrid),
+ * - die grep-artigen Faehigkeiten (Nutzerwunsch A4),
+ * - Ausgabeformate und Sortierung,
+ * - der Komplexitaets-Bias (vision.md §1b: Komplexitaet ist ein Blickwinkel
+ *   auf dieselbe Frage, kein zweites Werkzeug).
+ */
+import type { IndexFreshnessV1, SearchAbstention, SearchRequestV1, SkipLedgerEntryV1, ToolWarningV1 } from "@untangle-code/domain";
+/**
+ * Welche unabhaengigen Abruf- und Rankingzweige ausgefuehrt werden.
+ *
+ * - `hybrid` (Default): dicht + lexikalisch + exakter Symbolname, fusioniert;
+ * - `semantic`: nur der dichte Zweig;
+ * - `lexical`: nur BM25;
+ * - `symbol`: nur der exakte Symbolnamen-Abrufzweig.
+ *
+ * Lexikalische und Symbolsuche erzeugen kein Queryembedding. Ein
+ * eingeschraenkter Modus laesst die anderen Abrufzweige weg; Fusion und
+ * Score-Zerlegung bleiben dieselben. Genau deshalb
+ * bleibt ein `lexical`-Ergebnis mit einem `hybrid`-Ergebnis vergleichbar
+ * lesbar — es fehlen nur Bestandteile, es sind keine anderen.
+ */
+export declare const SEARCH_MODES: readonly ["hybrid", "semantic", "lexical", "symbol"];
+export type SearchMode = (typeof SEARCH_MODES)[number];
+export { SEARCH_ABSTENTIONS } from "@untangle-code/domain";
+export type { SearchAbstention };
+/**
+ * Ausdrueckliche Bevorzugung einfacher oder komplexer Treffer (vision.md §1b).
+ *
+ * Default ist `none`. Das ist eine Entscheidung, keine Bequemlichkeit:
+ * Komplexitaet DARF die Rangfolge nicht stillschweigend verschieben. Wer sie
+ * einbezieht, bekommt dafuer einen sichtbaren `complexity_modifier` in der
+ * Score-Zerlegung.
+ */
+export declare const COMPLEXITY_BIASES: readonly ["none", "prefer-simple", "prefer-complex"];
+export type ComplexityBias = (typeof COMPLEXITY_BIASES)[number];
+/** Sortierschluessel der Trefferliste (Nutzerwunsch A4: „Sortierung"). */
+export declare const SEARCH_SORTS: readonly ["relevance", "path", "complexity-desc", "complexity-asc", "findability-asc"];
+export type SearchSort = (typeof SEARCH_SORTS)[number];
+/** Ausgabeformate (Nutzerwunsch A4: „Text, JSON, JSONL"). */
+export declare const OUTPUT_FORMATS: readonly ["text", "json", "jsonl"];
+export type OutputFormat = (typeof OUTPUT_FORMATS)[number];
+/**
+ * Suchanfrage des Abrufkerns: die Spezifikationsform aus spec.md §13.1 plus
+ * die Erweiterungen dieses Pakets. Additiv — jede gueltige `SearchRequestV1`
+ * ist auch eine gueltige `UntangleSearchRequestV1`.
+ */
+export interface UntangleSearchRequestV1 extends SearchRequestV1 {
+    mode?: SearchMode;
+    /**
+     * Verhalten bei unzureichender Evidenz. Fehlt es, gilt `strict` — das ist
+     * byte-identisch zum Verhalten vor Welle 14, bis in beide Fingerprints.
+     */
+    abstention?: SearchAbstention;
+    /** Pfadmuster, die AUSGESCHLOSSEN werden (Gegenstueck zu `pathGlob`). */
+    pathExclude?: string[];
+    /** Chunk-Inhalt mitliefern; Default false (tokenarm fuer Agents). */
+    includeContent?: boolean;
+    complexityBias?: ComplexityBias;
+    sort?: SearchSort;
+    /** Nur Treffer mit Findability-Score <= diesem Wert (vision.md §1d). */
+    findabilityMaxScore?: number;
+    /** Nur Treffer mit Findability-Score >= diesem Wert. */
+    findabilityMinScore?: number;
+}
+/**
+ * Normalisierte Zusatzangaben — das Gegenstueck zu `SearchQueryV1` fuer die
+ * Felder, die dieses Paket ergaenzt. Alle Felder sind gesetzt (keine
+ * `undefined`-Faelle mehr), damit der Ausfuehrungspfad keine Defaults mehr
+ * erraten muss.
+ */
+export interface SearchQueryExtensionsV1 {
+    mode: SearchMode;
+    abstention: SearchAbstention;
+    pathExcludes: string[];
+    includeContent: boolean;
+    complexityBias: ComplexityBias;
+    sort: SearchSort;
+}
+/** Sortierung der grep-Treffer. */
+export declare const GREP_SORTS: readonly ["path", "matches-desc"];
+export type GrepSort = (typeof GREP_SORTS)[number];
+/**
+ * Regex-/Literalsuche ueber den INDEXIERTEN Inhalt.
+ *
+ * Wichtig fuer das Verstaendnis der Ergebnisse: gesucht wird im Index, nicht
+ * auf der Platte. Ein nicht indizierter oder wegen Groesse uebersprungener
+ * Inhalt kann hier nicht gefunden werden — deshalb traegt das Ergebnis den
+ * Skip-Ledger mit, statt schlicht „nichts gefunden" zu behaupten (E4).
+ */
+export interface GrepRequestV1 {
+    /** Suchmuster; regulaerer Ausdruck, wenn `regex` true ist, sonst Literal. */
+    pattern: string;
+    regex?: boolean;
+    caseSensitive?: boolean;
+    /** Nur ganze Woerter (Bezeichnergrenzen). */
+    wholeWord?: boolean;
+    workspaceId?: string;
+    repositories?: string[];
+    refs?: string[];
+    languages?: string[];
+    pathGlob?: string[];
+    pathExclude?: string[];
+    /** Kontextzeilen vor bzw. nach der Trefferzeile. */
+    contextLinesBefore?: number;
+    contextLinesAfter?: number;
+    /** Obergrenze der zurueckgegebenen Treffer insgesamt. */
+    maxMatches?: number;
+    /** Obergrenze je Datei; verhindert, dass eine Datei die Liste fuellt. */
+    maxMatchesPerFile?: number;
+    /**
+     * Obergrenze der durchsuchten Chunks. Schuetzt vor pathologischen
+     * Ausdruecken und riesigen Indizes; Ueberschreitung ist ein sichtbarer
+     * Abbruchgrund, kein stilles Kuerzen.
+     */
+    maxScannedChunks?: number;
+    sort?: GrepSort;
+}
+/** Eine Kontextzeile eines grep-Treffers. */
+export interface GrepContextLineV1 {
+    /** 1-basierte Zeilennummer in der Datei. */
+    line: number;
+    text: string;
+}
+/** Ein einzelner grep-Treffer mit Herkunft und Kontext. */
+export interface GrepMatchV1 {
+    repoId: string;
+    repoLabel: string;
+    refId: string;
+    refName: string;
+    commitSha?: string;
+    fileId: string;
+    /** „/"-normalisierter, repo-relativer Pfad. */
+    filePath: string;
+    language: string;
+    chunkId: string;
+    symbolName?: string;
+    /** 1-basierte Zeilennummer in der Datei. */
+    line: number;
+    /** 1-basierte Spalte des Treffers innerhalb der Zeile (UTF-16-Einheiten). */
+    column: number;
+    /** Der getroffene Text selbst. */
+    matchText: string;
+    /** Die vollstaendige Trefferzeile. */
+    lineText: string;
+    before: GrepContextLineV1[];
+    after: GrepContextLineV1[];
+}
+/** Ergebnis einer grep-Ausfuehrung. */
+export interface GrepResultSetV1 {
+    schemaVersion: 1;
+    indexFreshness?: IndexFreshnessV1;
+    pattern: string;
+    isRegex: boolean;
+    matches: GrepMatchV1[];
+    totalMatches: number;
+    /** True, wenn eine Grenze griff; dann ist `truncationReason` Pflicht (E4). */
+    truncated: boolean;
+    truncationReason?: "max_matches" | "max_matches_per_file" | "max_scanned_chunks";
+    scannedChunks: number;
+    skipped: SkipLedgerEntryV1[];
+    warnings: ToolWarningV1[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,42 @@
+/**
+ * Welche unabhaengigen Abruf- und Rankingzweige ausgefuehrt werden.
+ *
+ * - `hybrid` (Default): dicht + lexikalisch + exakter Symbolname, fusioniert;
+ * - `semantic`: nur der dichte Zweig;
+ * - `lexical`: nur BM25;
+ * - `symbol`: nur der exakte Symbolnamen-Abrufzweig.
+ *
+ * Lexikalische und Symbolsuche erzeugen kein Queryembedding. Ein
+ * eingeschraenkter Modus laesst die anderen Abrufzweige weg; Fusion und
+ * Score-Zerlegung bleiben dieselben. Genau deshalb
+ * bleibt ein `lexical`-Ergebnis mit einem `hybrid`-Ergebnis vergleichbar
+ * lesbar — es fehlen nur Bestandteile, es sind keine anderen.
+ */
+export const SEARCH_MODES = ["hybrid", "semantic", "lexical", "symbol"];
+// Aus dem Domain re-exportiert, damit Aufrufer nur EIN Paket brauchen.
+export { SEARCH_ABSTENTIONS } from "@untangle-code/domain";
+/**
+ * Ausdrueckliche Bevorzugung einfacher oder komplexer Treffer (vision.md §1b).
+ *
+ * Default ist `none`. Das ist eine Entscheidung, keine Bequemlichkeit:
+ * Komplexitaet DARF die Rangfolge nicht stillschweigend verschieben. Wer sie
+ * einbezieht, bekommt dafuer einen sichtbaren `complexity_modifier` in der
+ * Score-Zerlegung.
+ */
+export const COMPLEXITY_BIASES = ["none", "prefer-simple", "prefer-complex"];
+/** Sortierschluessel der Trefferliste (Nutzerwunsch A4: „Sortierung"). */
+export const SEARCH_SORTS = [
+    "relevance",
+    "path",
+    "complexity-desc",
+    "complexity-asc",
+    "findability-asc",
+];
+/** Ausgabeformate (Nutzerwunsch A4: „Text, JSON, JSONL"). */
+export const OUTPUT_FORMATS = ["text", "json", "jsonl"];
+// ---------------------------------------------------------------------------
+// grep-Modus (Nutzerwunsch A4)
+// ---------------------------------------------------------------------------
+/** Sortierung der grep-Treffer. */
+export const GREP_SORTS = ["path", "matches-desc"];
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,CAAU,CAAC;AAIjF,uEAAuE;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAG3D;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE,eAAe,EAAE,gBAAgB,CAAU,CAAC;AAItF,0EAA0E;AAC1E,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,WAAW;IACX,MAAM;IACN,iBAAiB;IACjB,gBAAgB;IAChB,iBAAiB;CACT,CAAC;AAIX,6DAA6D;AAC7D,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAU,CAAC;AA2CjE,8EAA8E;AAC9E,+BAA+B;AAC/B,8EAA8E;AAE9E,mCAAmC;AACnC,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,cAAc,CAAU,CAAC"}

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@untangle-code/search",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "description": "Untangle retrieval core: hybrid search (dense + deterministic BM25 + exact symbol names) with reciprocal rank fusion, explainable score breakdowns, complexity/findability filters, grep mode and deterministic output formats (spec.md §13, vision.md §1b/§1d).",
+  "license": "AGPL-3.0-only",
+  "homepage": "https://github.com/lboel/untangle",
+  "bugs": {
+    "url": "https://github.com/lboel/untangle/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lboel/untangle.git",
+    "directory": "packages/search"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": "^22.13.0 || >=24.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/test-helpers.*",
+    "!dist/**/test-support.*",
+    "!dist/**/test-support/**",
+    "!dist/**/testing/**",
+    "!dist/**/__tests__/**",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/test-helpers.ts",
+    "!src/**/test-support.ts",
+    "!src/**/test-support/**",
+    "!src/**/testing/**",
+    "LICENSE",
+    "NOTICE",
+    "README.md",
+    "THIRD_PARTY_LICENSES.md"
+  ],
+  "dependencies": {
+    "@untangle-code/config": "0.1.1",
+    "@untangle-code/domain": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.7",
+    "typescript": "5.9.3",
+    "vitest": "3.2.7",
+    "@untangle-code/testkit": "0.1.1"
+  },
+  "scripts": {
+    "build": "node ../../scripts/tsc-build.mjs tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "vitest run",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
 }

package/src/benchmark-integrity.ts

@@ -0,0 +1,25 @@
+/**
+ * Harte Ehrlichkeitsgrenze fuer den Live-Benchmark.
+ *
+ * Der Search-Port degradiert ausgefallene Ziele absichtlich zu Warnungen,
+ * damit eine interaktive Suche andere Profile weiter anzeigen kann. Ein
+ * Benchmark darf diese Semantik nicht als Messwert missverstehen: ohne
+ * ausgefuehrten Abruf sind null Treffer weder Akzeptanz noch Abstention.
+ */
+import type { SearchResultSetV1 } from "@untangle-code/domain";
+
+import { detectRetrievalFailure } from "./findability.js";
+
+/** Wirft, bevor ein Benchmark eine nicht ausgefuehrte Suche serialisieren kann. */
+export function assertBenchmarkRetrievalCompleted(
+  questionId: string,
+  result: SearchResultSetV1,
+): void {
+  const failure = detectRetrievalFailure(result);
+  if (failure === undefined) {
+    return;
+  }
+  throw new Error(
+    `benchmark row "${questionId}" is invalid because retrieval did not complete (${failure.reason}): ${failure.detail}`,
+  );
+}