@untangle-code/search 0.0.0-stage → 0.1.0

package/dist/findability.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Findability als Eigenschaft je Symbol (vision.md §1d).
+ *
+ * Die These, um die es hier geht, steht woertlich in vision.md §1d:
+ *
+ * > Wenn die Suche nach „Funktion X" nicht schnell an der richtigen Stelle
+ * > landet, ist das ein Befund ueber den Code — nicht nur ueber die Suche.
+ *
+ * Deshalb sucht sich hier ein Symbol SELBST: einmal mit seinem Namen, einmal
+ * mit seiner Signatur. Was dabei herauskommt — Rang, Streuung der Treffer,
+ * Sprungzahl — ist die Messung. Dass die Score-Zerlegung des Abrufkerns dabei
+ * mitlaeuft, ist kein Zufall: ohne sie liesse sich „der richtige Treffer
+ * rankt niedrig" nicht von „es gibt gar keinen Treffer" unterscheiden, und das
+ * sind zwei VERSCHIEDENE Befunde ueber den Code.
+ *
+ * ALLES HIER IST HEURISTIK, und die Domain erzwingt das strukturell:
+ * `isHeuristic` ist auf `true` typisiert, die Confidence auf `heuristic`
+ * festgenagelt. Ein Findability-Wert kann deshalb nirgends die Stelle eines
+ * gemessenen Complexity-Werts einnehmen.
+ */
+import type { Clock, FindabilityDiagnosisBasisV1, FindabilityDiagnosisV1, FindabilityDispersionV1, FindabilityHopsV1, FindabilityOutcomeV1, FindabilityRetrievalUnavailableReason, FindabilityUnavailableV1, PortCallOptions, SearchResultSetV1, SkipLedgerEntryV1 } from "@untangle-code/domain";
+import type { SearchPort } from "./port.js";
+/** Das Symbol, dessen Auffindbarkeit gemessen wird. */
+export interface FindabilitySubject {
+    workspaceId: string;
+    repoId: string;
+    refId: string;
+    symbolId: string;
+    symbolName: string;
+    symbolFqn: string;
+    /** „/"-normalisierter, repo-relativer Pfad. */
+    filePath: string;
+    signature?: string;
+}
+/** Liefert die Sprungzahl vom Rang-1-Treffer zum Zielsymbol (Symbolgraph). */
+export type HopsLookup = (input: {
+    fromSymbolId: string;
+    toSymbolId: string;
+}) => FindabilityHopsV1 | undefined;
+export interface FindabilityOptions {
+    /** Wie viele Treffer eine Sonde anfordert; Default 10. */
+    probeLimit?: number;
+    hops?: HopsLookup;
+    generationId: string;
+    /**
+     * Optionale Vorpruefung: ist das Symbol ueberhaupt indexiert? Fehlt sie,
+     * wird nicht geraten — dann bleibt nur, was die Suche selbst meldet.
+     * Antwortet sie `false`, entsteht ein Zustandsvermerk statt einer Messung:
+     * ein nicht indexiertes Symbol findet sich nicht, und das sagt nichts ueber
+     * seinen Code (vision.md §1d).
+     */
+    isSymbolIndexed?: (symbolId: string) => boolean;
+}
+/**
+ * Schwellen der Diagnose. Sie sind Politik, keine Naturkonstanten — deshalb
+ * stehen sie hier benannt und werden in jedem Beleg (`threshold`) mitgeliefert,
+ * damit ein Leser die Aussage nachrechnen kann.
+ */
+export declare const FINDABILITY_THRESHOLDS: {
+    /** Ab diesem Rang gilt der eigene Treffer als „rankt niedrig". */
+    readonly weakRank: 3;
+    /** Ab dieser Streuung gilt die Verantwortlichkeit als zerfasert. */
+    readonly scatteredDispersion: 0.6;
+    /** Ab dieser Sprungzahl gilt der Weg als zu verflochten. */
+    readonly entangledHops: 2;
+};
+/** Benannte Formel hinter `FindabilityDispersionV1.dispersion`. */
+export declare const DISPERSION_FORMULA = "(matchedFileCount - 1) / max(1, matchedHitCount - 1), clamped to [0, 1]";
+/** Benannte Formel hinter `FindabilityV1.score`. */
+export declare const FINDABILITY_SCORE_FORMULA = "0.5*rankScore(nameProbe) + 0.2*rankScore(signatureProbe) + 0.2*(1 - dispersion) + 0.1*hopScore, with rankScore(r) = 0 for no rank else 1/r, hopScore = 0.5 when hops are unknown else 1/(1+hops)";
+/** Rangwert einer Sonde: Rang 1 → 1.0, Rang 2 → 0.5, kein Rang → 0. */
+export declare function rankScore(rank: number | null): number;
+/** Streuung ueber Dateien (siehe {@link DISPERSION_FORMULA}). */
+export declare function computeDispersion(filePaths: readonly string[], ownFileHitCount: number): FindabilityDispersionV1;
+/**
+ * Leitet die benannten Ursachen aus den Messwerten ab (vision.md §1d Tabelle).
+ *
+ * Nimmt bewusst KEINE losen Sonden entgegen, sondern nur einen
+ * {@link FindabilityDiagnosisBasisV1} — den Nachweis aus `packages/domain`,
+ * dass der Abruf tatsaechlich gelaufen ist. Ein Zustandsvermerk
+ * (`FindabilityUnavailableV1`) ist auf diesen Typ nicht zuweisbar, eine
+ * ausgefallene Sonde bekommt gar keinen Nachweis. Damit ist es im TYP
+ * unmoeglich, aus einem Werkzeugversagen eine Aussage ueber den Code zu
+ * machen — genau der Denkfehler, den vision.md §1d frueher offen liess.
+ */
+export declare function diagnose(subject: FindabilitySubject, basis: FindabilityDiagnosisBasisV1): FindabilityDiagnosisV1[];
+/**
+ * Warncodes, mit denen der Abrufkern ein AUSGEFALLENES Suchziel meldet.
+ *
+ * Diese Liste ist noetig, weil `UntangleSearchEngine` ein ausgefallenes Ziel
+ * NICHT wirft, sondern nach spec.md §25.2 sichtbar degradiert: das Ergebnis
+ * kommt mit einer Gruppe weniger — im schlimmsten Fall ganz ohne Gruppe — und
+ * einer Warnung zurueck. Wer nur auf `hits.length` schaut, liest dann „kein
+ * Treffer", und genau daraus entstuende die falsche Aussage ueber den Code.
+ */
+export declare const FINDABILITY_RETRIEVAL_FAILURE_WARNING_CODES: readonly ["EMBEDDING_DIMENSION_MISMATCH", "EMBEDDING_UNAVAILABLE", "INDEX_INCOMPLETE", "INDEX_PROFILE_MISMATCH", "PROFILE_UNAVAILABLE", "QDRANT_SCHEMA_INCOMPATIBLE", "LANCEDB_UNAVAILABLE", "LANCEDB_SCHEMA_INCOMPATIBLE", "QDRANT_UNAVAILABLE", "SEARCH_BRANCH_UNAVAILABLE"];
+/** Grund plus Begruendung fuer einen Zustandsvermerk. */
+export interface FindabilityRetrievalFailureV1 {
+    reason: FindabilityRetrievalUnavailableReason;
+    detail: string;
+}
+/**
+ * Prueft ein Suchergebnis darauf, ob die Suche wirklich gelaufen ist.
+ *
+ * `undefined` heisst: sie lief. Alles andere ist ein Zustandsvermerk, kein
+ * Messwert. Eine Ergebnismenge ohne jede Profilgruppe zaehlt dabei als
+ * Ausfall — ohne Profil hat niemand gesucht, und „nichts gefunden" waere eine
+ * Behauptung ueber den Code, die auf keiner Beobachtung steht.
+ *
+ * DASSELBE GILT FUER EINE GRUPPE, DIE NICHT DURCHSUCHT WURDE (Befund B1 der
+ * Nachpruefung, Fall B). Liegt der Geltungsbereich der Sonde — Workspace,
+ * Repository, Ref des Symbols — vollstaendig ausserhalb der verdrahteten
+ * Ziele, liefert der Abrufkern trotzdem eine Gruppe: leer, mit
+ * `notSearchedReason` und einem Eintrag im Skip-Ledger. Wer nur `groups.length`
+ * zaehlt, sieht eine Gruppe und haelt die Sonde fuer gelaufen — und veroeffent-
+ * licht danach „no_match" und die Diagnose „undocumented" ueber ein Symbol,
+ * nach dem nie gesucht wurde. Deshalb zaehlen hier nur Gruppen, die
+ * TATSAECHLICH durchsucht wurden.
+ */
+export declare function detectRetrievalFailure(set: SearchResultSetV1): FindabilityRetrievalFailureV1 | undefined;
+/**
+ * Uebersetzt einen Zustandsvermerk in einen Skip-Ledger-Eintrag (E4). Ein
+ * ausgefallener Abruf darf nicht nur im Datensatz stehen, sondern gehoert in
+ * dieselbe Liste wie jede andere Auslassung.
+ */
+export declare function findabilitySkipEntry(note: FindabilityUnavailableV1): SkipLedgerEntryV1;
+/**
+ * Misst die Auffindbarkeit eines Symbols mit zwei Selbstsonden.
+ *
+ * Der Aufrufer stellt den Port; diese Funktion macht nichts anderes, als ihn
+ * zweimal zu fragen und das Ergebnis ehrlich zu verbuchen — insbesondere den
+ * Fall „nicht gefunden", der als Rang `null` MIT benanntem Grund im Datensatz
+ * steht und nicht als fehlender Wert verschwindet (E4).
+ *
+ * ZWEI ERGEBNISSE, NICHT EINS (vision.md §1d): lief die Suche, kommt eine
+ * `FindabilityV1`-MESSUNG zurueck. Lief sie nicht — Speicher nicht
+ * erreichbar, Profil fehlt, Symbol nicht indexiert —, kommt ein
+ * `FindabilityUnavailableV1`-ZUSTANDSVERMERK zurueck. Der traegt keinen Score
+ * und keine Diagnose, weil ein Werkzeugversagen kein Befund ueber den Code
+ * ist. Aufrufer MUESSEN die beiden Faelle unterscheiden; der Typ zwingt sie
+ * dazu.
+ */
+export declare function measureFindability(port: SearchPort, subject: FindabilitySubject, clock: Clock, options: FindabilityOptions, callOptions?: PortCallOptions): Promise<FindabilityOutcomeV1>;
+//# sourceMappingURL=findability.d.ts.map

package/dist/findability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"findability.d.ts","sourceRoot":"","sources":["../src/findability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EACV,KAAK,EACL,2BAA2B,EAC3B,sBAAsB,EACtB,uBAAuB,EAEvB,iBAAiB,EACjB,oBAAoB,EAIpB,qCAAqC,EACrC,wBAAwB,EAExB,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,uBAAuB,CAAC;AAY/B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C,uDAAuD;AACvD,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,8EAA8E;AAC9E,MAAM,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB,KAAK,iBAAiB,GAAG,SAAS,CAAC;AAEpC,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC;CACjD;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;IACjC,kEAAkE;;IAElE,oEAAoE;;IAEpE,4DAA4D;;CAEpD,CAAC;AAEX,mEAAmE;AACnE,eAAO,MAAM,kBAAkB,4EAC4C,CAAC;AAE5E,oDAAoD;AACpD,eAAO,MAAM,yBAAyB,qMAC8J,CAAC;AAErM,uEAAuE;AACvE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAErD;AA0ED,iEAAiE;AACjE,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,eAAe,EAAE,MAAM,GACtB,uBAAuB,CAMzB;AAkBD;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,2BAA2B,GACjC,sBAAsB,EAAE,CA8E1B;AAMD;;;;;;;;GAQG;AACH,eAAO,MAAM,2CAA2C,gRAW9C,CAAC;AAEX,yDAAyD;AACzD,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,qCAAqC,CAAC;IAC9C,MAAM,EAAE,MAAM,CAAC;CAChB;AAQD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,iBAAiB,GACrB,6BAA6B,GAAG,SAAS,CAwB3C;AAQD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,wBAAwB,GAAG,iBAAiB,CAYtF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,kBAAkB,EAC3B,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,kBAAkB,EAC3B,WAAW,CAAC,EAAE,eAAe,GAC5B,OAAO,CAAC,oBAAoB,CAAC,CA8I/B"}

package/dist/findability.js

@@ -0,0 +1,393 @@
+import { FINDABILITY_ALGORITHM_ID, RANKER_VERSION, buildFindabilityId, buildSkipLedgerEntry, isUntangleError, makeFindabilityUnavailable, openFindabilityDiagnosisBasis, sortByCodepoints, } from "@untangle-code/domain";
+/**
+ * Schwellen der Diagnose. Sie sind Politik, keine Naturkonstanten — deshalb
+ * stehen sie hier benannt und werden in jedem Beleg (`threshold`) mitgeliefert,
+ * damit ein Leser die Aussage nachrechnen kann.
+ */
+export const FINDABILITY_THRESHOLDS = {
+    /** Ab diesem Rang gilt der eigene Treffer als „rankt niedrig". */
+    weakRank: 3,
+    /** Ab dieser Streuung gilt die Verantwortlichkeit als zerfasert. */
+    scatteredDispersion: 0.6,
+    /** Ab dieser Sprungzahl gilt der Weg als zu verflochten. */
+    entangledHops: 2,
+};
+/** Benannte Formel hinter `FindabilityDispersionV1.dispersion`. */
+export const DISPERSION_FORMULA = "(matchedFileCount - 1) / max(1, matchedHitCount - 1), clamped to [0, 1]";
+/** Benannte Formel hinter `FindabilityV1.score`. */
+export const FINDABILITY_SCORE_FORMULA = "0.5*rankScore(nameProbe) + 0.2*rankScore(signatureProbe) + 0.2*(1 - dispersion) + 0.1*hopScore, with rankScore(r) = 0 for no rank else 1/r, hopScore = 0.5 when hops are unknown else 1/(1+hops)";
+/** Rangwert einer Sonde: Rang 1 → 1.0, Rang 2 → 0.5, kein Rang → 0. */
+export function rankScore(rank) {
+    return rank === null ? 0 : 1 / rank;
+}
+function heuristicConfidence(value, signals) {
+    return { value, basis: "heuristic", signals };
+}
+function evaluateProbe(kind, queryText, subject, set) {
+    // Alle Gruppen zusammen: eine Sonde fragt nach EINEM Symbol, und in welcher
+    // Profilgruppe es auftaucht, ist fuer die Auffindbarkeit unerheblich. Die
+    // Raenge bleiben gruppenintern korrekt, weil die Sonde den Rang des eigenen
+    // Treffers innerhalb SEINER Gruppe liest.
+    const hits = set.groups.flatMap((group) => group.hits);
+    const own = hits.find((hit) => hit.symbolId === subject.symbolId);
+    const topScore = hits[0]?.score.final;
+    const probe = {
+        kind,
+        queryText,
+        queryFingerprint: set.queryFingerprint,
+        rank: own === undefined ? null : own.rank,
+        ...(own === undefined ? { rankMissingReason: rankMissingReasonFor(set, hits.length) } : {}),
+        hitCount: hits.length,
+        ...(topScore === undefined ? {} : { topScore }),
+        ...(own === undefined ? {} : { selfScore: own.score.final }),
+    };
+    return {
+        probe,
+        filePaths: hits.map((hit) => hit.filePath),
+        hitCount: hits.length,
+        ownFileHitCount: hits.filter((hit) => hit.filePath === subject.filePath).length,
+    };
+}
+/**
+ * Warum eine Sonde keinen Rang ergab — aus der ENTSCHEIDUNG, nie aus der
+ * Listenlaenge.
+ *
+ * Vorher stand hier `hits.length === 0 ? "no_match" : "outside_result_limit"`.
+ * Beide sind Behauptungen ueber den CODE. Eine Enthaltung ist aber eine
+ * Aussage ueber die KALIBRIERUNG: der Abruf lief, es gab Kandidaten, und die
+ * Policy hielt die Evidenz fuer unzureichend. Als `no_match` veroeffentlicht
+ * wurde daraus „dazu gibt es nichts" — und ein Symbol, das fuer seinen eigenen
+ * Namen auf Rang 1 stuende, galt als unauffindbar.
+ */
+function rankMissingReasonFor(set, hitCount) {
+    if (set.groups.some((group) => group.relevanceDecision?.status === "rejected")) {
+        return "relevance_policy_rejected";
+    }
+    // Kein Kandidat hat den Abruf ueberhaupt erreicht: dann ist „nichts
+    // gefunden" eine belegte Aussage und keine Vermutung.
+    if (set.groups.length > 0 &&
+        set.groups.every((group) => group.retrieval?.deduplicatedCandidateCount === 0)) {
+        return "no_match";
+    }
+    return hitCount === 0 ? "no_match" : "outside_result_limit";
+}
+/** Streuung ueber Dateien (siehe {@link DISPERSION_FORMULA}). */
+export function computeDispersion(filePaths, ownFileHitCount) {
+    const matchedHitCount = filePaths.length;
+    const matchedFileCount = new Set(filePaths).size;
+    const raw = (matchedFileCount - 1) / Math.max(1, matchedHitCount - 1);
+    const dispersion = Math.min(1, Math.max(0, raw));
+    return { matchedFileCount, matchedHitCount, ownFileHitCount, dispersion };
+}
+function evidence(kind, observedValue, threshold, references, note) {
+    return {
+        kind,
+        observedValue,
+        threshold,
+        references,
+        ...(note === undefined ? {} : { note }),
+    };
+}
+/**
+ * Leitet die benannten Ursachen aus den Messwerten ab (vision.md §1d Tabelle).
+ *
+ * Nimmt bewusst KEINE losen Sonden entgegen, sondern nur einen
+ * {@link FindabilityDiagnosisBasisV1} — den Nachweis aus `packages/domain`,
+ * dass der Abruf tatsaechlich gelaufen ist. Ein Zustandsvermerk
+ * (`FindabilityUnavailableV1`) ist auf diesen Typ nicht zuweisbar, eine
+ * ausgefallene Sonde bekommt gar keinen Nachweis. Damit ist es im TYP
+ * unmoeglich, aus einem Werkzeugversagen eine Aussage ueber den Code zu
+ * machen — genau der Denkfehler, den vision.md §1d frueher offen liess.
+ */
+export function diagnose(subject, basis) {
+    const { nameProbe, dispersion, hops } = basis;
+    const diagnoses = [];
+    // Die Fallunterscheidung folgt der Tabelle aus vision.md §1d:
+    //   „Gar kein passender Treffer"  -> das Symbol taucht in seinen eigenen
+    //     Suchergebnissen NICHT auf   -> `undocumented`;
+    //   „Der richtige Treffer rankt niedrig" -> es taucht auf, aber weit unten
+    //                                 -> `weak-naming`.
+    // Wichtig: „kein Rang" heisst NICHT „keine Treffer". Der dichte Zweig
+    // liefert fast immer irgendetwas; entscheidend ist, ob das GESUCHTE Symbol
+    // darunter ist.
+    if (nameProbe.rank === null) {
+        diagnoses.push({
+            cause: "undocumented",
+            confidence: heuristicConfidence(nameProbe.hitCount === 0 ? 0.6 : 0.5, [
+                "self_not_in_own_name_results",
+                ...(nameProbe.hitCount === 0 ? ["no_results_at_all"] : ["other_results_ranked_instead"]),
+            ]),
+            evidence: [
+                evidence("hit_count", nameProbe.hitCount, 1, [subject.symbolFqn], "searching for the symbol's own name did not return the symbol itself"),
+            ],
+            isHeuristic: true,
+            note: "the symbol's own name does not retrieve it; either the name carries no intent or nothing describes it",
+        });
+    }
+    else if (nameProbe.rank > FINDABILITY_THRESHOLDS.weakRank) {
+        diagnoses.push({
+            cause: "weak-naming",
+            confidence: heuristicConfidence(0.5, ["self_rank_below_threshold"]),
+            evidence: [
+                evidence("self_rank", nameProbe.rank, FINDABILITY_THRESHOLDS.weakRank, [subject.symbolFqn], "the symbol does not rank near the top for its own name"),
+            ],
+            isHeuristic: true,
+        });
+    }
+    if (dispersion.dispersion > FINDABILITY_THRESHOLDS.scatteredDispersion) {
+        diagnoses.push({
+            cause: "scattered-responsibility",
+            confidence: heuristicConfidence(0.5, ["high_file_dispersion"]),
+            evidence: [
+                evidence("matched_file_count", dispersion.matchedFileCount, FINDABILITY_THRESHOLDS.scatteredDispersion, [subject.filePath], `hits spread over ${dispersion.matchedFileCount} files (dispersion ${dispersion.dispersion.toFixed(3)})`),
+            ],
+            isHeuristic: true,
+        });
+    }
+    if (hops.hops !== null && hops.hops > FINDABILITY_THRESHOLDS.entangledHops) {
+        diagnoses.push({
+            cause: "high-entanglement",
+            confidence: heuristicConfidence(hops.pathUsesUncertainEdges ? 0.4 : 0.6, [
+                "hop_count_above_threshold",
+                ...(hops.pathUsesUncertainEdges ? ["path_uses_uncertain_edges"] : []),
+            ]),
+            evidence: [evidence("hop_count", hops.hops, FINDABILITY_THRESHOLDS.entangledHops, hops.path)],
+            isHeuristic: true,
+        });
+    }
+    return diagnoses;
+}
+// ---------------------------------------------------------------------------
+// Lief die Suche ueberhaupt? (vision.md §1d)
+// ---------------------------------------------------------------------------
+/**
+ * Warncodes, mit denen der Abrufkern ein AUSGEFALLENES Suchziel meldet.
+ *
+ * Diese Liste ist noetig, weil `UntangleSearchEngine` ein ausgefallenes Ziel
+ * NICHT wirft, sondern nach spec.md §25.2 sichtbar degradiert: das Ergebnis
+ * kommt mit einer Gruppe weniger — im schlimmsten Fall ganz ohne Gruppe — und
+ * einer Warnung zurueck. Wer nur auf `hits.length` schaut, liest dann „kein
+ * Treffer", und genau daraus entstuende die falsche Aussage ueber den Code.
+ */
+export const FINDABILITY_RETRIEVAL_FAILURE_WARNING_CODES = [
+    "EMBEDDING_DIMENSION_MISMATCH",
+    "EMBEDDING_UNAVAILABLE",
+    "INDEX_INCOMPLETE",
+    "INDEX_PROFILE_MISMATCH",
+    "PROFILE_UNAVAILABLE",
+    "QDRANT_SCHEMA_INCOMPATIBLE",
+    "LANCEDB_UNAVAILABLE",
+    "LANCEDB_SCHEMA_INCOMPATIBLE",
+    "QDRANT_UNAVAILABLE",
+    "SEARCH_BRANCH_UNAVAILABLE",
+];
+function reasonForCode(code) {
+    if (code === "INDEX_PROFILE_MISMATCH")
+        return "search_profile_missing";
+    if (code === "INDEX_INCOMPLETE")
+        return "symbol_not_indexed";
+    return "search_unavailable";
+}
+/**
+ * Prueft ein Suchergebnis darauf, ob die Suche wirklich gelaufen ist.
+ *
+ * `undefined` heisst: sie lief. Alles andere ist ein Zustandsvermerk, kein
+ * Messwert. Eine Ergebnismenge ohne jede Profilgruppe zaehlt dabei als
+ * Ausfall — ohne Profil hat niemand gesucht, und „nichts gefunden" waere eine
+ * Behauptung ueber den Code, die auf keiner Beobachtung steht.
+ *
+ * DASSELBE GILT FUER EINE GRUPPE, DIE NICHT DURCHSUCHT WURDE (Befund B1 der
+ * Nachpruefung, Fall B). Liegt der Geltungsbereich der Sonde — Workspace,
+ * Repository, Ref des Symbols — vollstaendig ausserhalb der verdrahteten
+ * Ziele, liefert der Abrufkern trotzdem eine Gruppe: leer, mit
+ * `notSearchedReason` und einem Eintrag im Skip-Ledger. Wer nur `groups.length`
+ * zaehlt, sieht eine Gruppe und haelt die Sonde fuer gelaufen — und veroeffent-
+ * licht danach „no_match" und die Diagnose „undocumented" ueber ein Symbol,
+ * nach dem nie gesucht wurde. Deshalb zaehlen hier nur Gruppen, die
+ * TATSAECHLICH durchsucht wurden.
+ */
+export function detectRetrievalFailure(set) {
+    const codes = new Set(FINDABILITY_RETRIEVAL_FAILURE_WARNING_CODES);
+    const failed = set.warnings.find((warning) => codes.has(warning.code));
+    if (failed !== undefined) {
+        return { reason: reasonForCode(failed.code), detail: `${failed.code}: ${failed.message}` };
+    }
+    if (set.groups.length === 0) {
+        return {
+            reason: "search_profile_missing",
+            detail: "the probe came back without a single profile group; no embedding profile answered, so nothing was actually searched",
+        };
+    }
+    const searched = set.groups.filter((group) => group.notSearchedReason === undefined);
+    if (searched.length === 0) {
+        const reasons = sortByCodepoints(set.groups.map((group) => group.notSearchedReason)).join("; ");
+        return {
+            reason: "probe_not_executed",
+            detail: `not one of the ${set.groups.length} profile group(s) was actually searched, so the probe observed nothing: ${reasons}`,
+        };
+    }
+    return undefined;
+}
+function failureForError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = isUntangleError(error) ? error.code : "SEARCH_FAILED";
+    return { reason: reasonForCode(code), detail: `${code}: ${message}` };
+}
+/**
+ * Uebersetzt einen Zustandsvermerk in einen Skip-Ledger-Eintrag (E4). Ein
+ * ausgefallener Abruf darf nicht nur im Datensatz stehen, sondern gehoert in
+ * dieselbe Liste wie jede andere Auslassung.
+ */
+export function findabilitySkipEntry(note) {
+    return buildSkipLedgerEntry({
+        stage: "findability",
+        subjectKind: "symbol",
+        subjectId: note.symbolId,
+        path: note.filePath,
+        repoId: note.repoId,
+        refId: note.refId,
+        reason: note.reason === "symbol_not_indexed" ? "missing_index_entry" : "provider_unavailable",
+        detail: `findability not measured for "${note.symbolFqn}" (${note.reason}): ${note.detail}`,
+        recoverable: true,
+    });
+}
+/**
+ * Misst die Auffindbarkeit eines Symbols mit zwei Selbstsonden.
+ *
+ * Der Aufrufer stellt den Port; diese Funktion macht nichts anderes, als ihn
+ * zweimal zu fragen und das Ergebnis ehrlich zu verbuchen — insbesondere den
+ * Fall „nicht gefunden", der als Rang `null` MIT benanntem Grund im Datensatz
+ * steht und nicht als fehlender Wert verschwindet (E4).
+ *
+ * ZWEI ERGEBNISSE, NICHT EINS (vision.md §1d): lief die Suche, kommt eine
+ * `FindabilityV1`-MESSUNG zurueck. Lief sie nicht — Speicher nicht
+ * erreichbar, Profil fehlt, Symbol nicht indexiert —, kommt ein
+ * `FindabilityUnavailableV1`-ZUSTANDSVERMERK zurueck. Der traegt keinen Score
+ * und keine Diagnose, weil ein Werkzeugversagen kein Befund ueber den Code
+ * ist. Aufrufer MUESSEN die beiden Faelle unterscheiden; der Typ zwingt sie
+ * dazu.
+ */
+export async function measureFindability(port, subject, clock, options, callOptions) {
+    const limit = options.probeLimit ?? 10;
+    const baseRequest = {
+        workspaceId: subject.workspaceId,
+        repositories: [subject.repoId],
+        refs: [subject.refId],
+        limit,
+        // Ausdruecklich gepinnt: eine veroeffentlichte Kennzahl darf nicht von
+        // einer ungepinnten Vorgabe abhaengen. Zoege der Default eines Tages nach
+        // `evidence`, bekaemen abgelehnte Sonden still einen Rang.
+        abstention: "strict",
+    };
+    const note = (failure, probeKinds) => makeFindabilityUnavailable({
+        workspaceId: subject.workspaceId,
+        repoId: subject.repoId,
+        refId: subject.refId,
+        symbolId: subject.symbolId,
+        symbolFqn: subject.symbolFqn,
+        filePath: subject.filePath,
+        reason: failure.reason,
+        detail: failure.detail,
+        probeKinds,
+        observedAt: clock.nowIso(),
+        generationId: options.generationId,
+    });
+    const bothProbes = ["self-name", "self-signature"];
+    if (options.isSymbolIndexed !== undefined && !options.isSymbolIndexed(subject.symbolId)) {
+        return note({
+            reason: "symbol_not_indexed",
+            detail: `symbol "${subject.symbolFqn}" is not in the index, so no probe could reach it`,
+        }, bothProbes);
+    }
+    let nameSet;
+    try {
+        nameSet = await port.search({ ...baseRequest, query: subject.symbolName }, callOptions);
+    }
+    catch (error) {
+        return note(failureForError(error), bothProbes);
+    }
+    const nameFailure = detectRetrievalFailure(nameSet);
+    if (nameFailure !== undefined)
+        return note(nameFailure, bothProbes);
+    const nameOutcome = evaluateProbe("self-name", subject.symbolName, subject, nameSet);
+    const signatureText = subject.signature ?? subject.symbolFqn;
+    let signatureSet;
+    try {
+        signatureSet = await port.search({ ...baseRequest, query: signatureText }, callOptions);
+    }
+    catch (error) {
+        return note(failureForError(error), ["self-signature"]);
+    }
+    const signatureFailure = detectRetrievalFailure(signatureSet);
+    if (signatureFailure !== undefined)
+        return note(signatureFailure, ["self-signature"]);
+    const signatureOutcome = evaluateProbe("self-signature", signatureText, subject, signatureSet);
+    const dispersion = computeDispersion([...nameOutcome.filePaths, ...signatureOutcome.filePaths], nameOutcome.ownFileHitCount + signatureOutcome.ownFileHitCount);
+    const topHit = nameSet.groups.flatMap((group) => group.hits)[0];
+    const hops = options.hops === undefined || topHit?.symbolId === undefined
+        ? {
+            hops: null,
+            hopsMissingReason: options.hops === undefined
+                ? "no_symbol_graph_lookup_wired"
+                : "top_hit_carries_no_symbol_id",
+            path: [],
+            pathUsesUncertainEdges: false,
+        }
+        : (options.hops({ fromSymbolId: topHit.symbolId, toSymbolId: subject.symbolId }) ?? {
+            hops: null,
+            hopsMissingReason: "no_path_in_symbol_graph",
+            path: [],
+            pathUsesUncertainEdges: false,
+        });
+    const hopScore = hops.hops === null ? 0.5 : 1 / (1 + hops.hops);
+    const score = 0.5 * rankScore(nameOutcome.probe.rank) +
+        0.2 * rankScore(signatureOutcome.probe.rank) +
+        0.2 * (1 - dispersion.dispersion) +
+        0.1 * hopScore;
+    const signals = [
+        "self_name_probe",
+        "self_signature_probe",
+        "file_dispersion",
+        hops.hops === null ? "hops_unknown" : "hop_count",
+    ];
+    // Letzte Instanz vor der Diagnose: der Nachweis aus `packages/domain`. Er
+    // bleibt aus, sobald eine Sonde ein Werkzeugversagen meldet — dann gibt es
+    // schlicht nichts, woraus sich eine Diagnose bilden LIESSE.
+    const basis = openFindabilityDiagnosisBasis({
+        nameProbe: nameOutcome.probe,
+        signatureProbe: signatureOutcome.probe,
+        dispersion,
+        hops,
+    });
+    return {
+        schemaVersion: 1,
+        findabilityId: buildFindabilityId({
+            workspaceId: subject.workspaceId,
+            symbolId: subject.symbolId,
+            algorithm: FINDABILITY_ALGORITHM_ID,
+            rankerVersion: RANKER_VERSION,
+        }),
+        workspaceId: subject.workspaceId,
+        repoId: subject.repoId,
+        refId: subject.refId,
+        symbolId: subject.symbolId,
+        symbolFqn: subject.symbolFqn,
+        filePath: subject.filePath,
+        algorithm: FINDABILITY_ALGORITHM_ID,
+        rankerVersion: RANKER_VERSION,
+        score: Math.min(1, Math.max(0, score)),
+        isHeuristic: true,
+        nameProbe: nameOutcome.probe,
+        signatureProbe: signatureOutcome.probe,
+        dispersion,
+        dispersionFormula: DISPERSION_FORMULA,
+        hops,
+        // Die Gesamt-Confidence sinkt, wenn ein Bestandteil fehlt: eine Messung
+        // ohne Sprungzahl ist weniger belastbar als eine mit.
+        confidence: heuristicConfidence(hops.hops === null ? 0.5 : 0.7, signals),
+        diagnoses: basis === undefined ? [] : diagnose(subject, basis),
+        measuredAt: clock.nowIso(),
+        generationId: options.generationId,
+    };
+}
+//# sourceMappingURL=findability.js.map

package/dist/findability.js.map

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

package/dist/format.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Ausgabeformate (Nutzerwunsch A4: „Text, JSON, JSONL").
+ *
+ * Drei Formate, drei Zwecke:
+ *
+ * - `text` — fuer Menschen im Terminal. Eine Zeile Kopf je Treffer, darunter
+ *   die Score-Zerlegung in Klartext. Die Zerlegung ist hier KEIN Debug-Anhang,
+ *   sondern der eigentliche Mehrwert: sie beantwortet „warum steht das oben?".
+ * - `json` — ein Dokument, vollstaendig, mit Ledger und Warnungen. Fuer
+ *   Werkzeuge, die das Ganze wollen.
+ * - `jsonl` — eine Zeile je Treffer, streambar. Fuer Agents und Pipes.
+ *   Die erste Zeile ist ein Kopfsatz mit Anfrage-Fingerabdruck, Warnungen und
+ *   Ledger — sonst wuerde beim Streamen genau die Information verloren gehen,
+ *   die E4 sichtbar machen soll.
+ *
+ * Alle drei sind deterministisch: gleiche Ergebnismenge, gleiche Bytes.
+ */
+import type { SearchGraphRelationsV1, SearchHitV1, SearchResultSetV1 } from "@untangle-code/domain";
+import type { GrepResultSetV1, OutputFormat } from "./types.js";
+/** Kompakte, aber vollstaendige Textdarstellung einer begrenzten Graphfacette. */
+export declare function formatSearchGraphRelationsAsText(label: "context" | "linked", value: SearchGraphRelationsV1): string[];
+/** Eine Trefferzeile plus Score-Zerlegung im Textformat. */
+export declare function formatHitAsText(hit: SearchHitV1): string;
+/** Formatiert eine ganze Ergebnismenge. */
+export declare function formatSearchResultSet(set: SearchResultSetV1, format: OutputFormat): string;
+/** Formatiert grep-Treffer. */
+export declare function formatGrepResultSet(set: GrepResultSetV1, format: OutputFormat): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAEV,sBAAsB,EACtB,WAAW,EACX,iBAAiB,EAClB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAahE,kFAAkF;AAClF,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,SAAS,GAAG,QAAQ,EAC3B,KAAK,EAAE,sBAAsB,GAC5B,MAAM,EAAE,CAgBV;AAED,4DAA4D;AAC5D,wBAAgB,eAAe,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CA0CxD;AAED,2CAA2C;AAC3C,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,iBAAiB,EAAE,MAAM,EAAE,YAAY,GAAG,MAAM,CA0E1F;AAED,+BAA+B;AAC/B,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,eAAe,EAAE,MAAM,EAAE,YAAY,GAAG,MAAM,CA6CtF"}