@untangle-code/search 0.0.0-stage → 0.1.1

package/dist/ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../src/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAG3E,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,iBAAiB,CAAC,aAAa,CAAC,CAAC;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;IAE5C,GAAG,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAgBxC,6DAA6D;IACtD,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,aAAa,CAAC,GAAG;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAI9F,IAAW,IAAI,IAAI,MAAM,CAExB;IAED,8DAA8D;IACvD,OAAO,IAAI,iBAAiB,EAAE;IAIrC,2EAA2E;IACpE,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;CAG7D"}

package/dist/ledger.js

@@ -0,0 +1,39 @@
+import { buildSkipLedgerEntry, summarizeSkipReasons } from "@untangle-code/domain";
+/**
+ * Sammelt Ledger-Eintraege einer einzelnen Suchausfuehrung.
+ *
+ * `add()` verweigert (ueber `buildSkipLedgerEntry`) eine leere Begruendung —
+ * ein Uebersprungeintrag ohne Grund taeuscht Diagnose vor, wo keine ist.
+ */
+export class SearchSkipLedger {
+    entries = [];
+    add(input) {
+        this.entries.push(buildSkipLedgerEntry({
+            stage: "search",
+            subjectKind: input.subjectKind,
+            ...(input.subjectId === undefined ? {} : { subjectId: input.subjectId }),
+            ...(input.path === undefined ? {} : { path: input.path }),
+            ...(input.repoId === undefined ? {} : { repoId: input.repoId }),
+            ...(input.refId === undefined ? {} : { refId: input.refId }),
+            reason: input.reason,
+            detail: input.detail,
+            recoverable: input.recoverable ?? false,
+        }));
+    }
+    /** Ein Kandidat, der die Trefferliste nicht erreicht hat. */
+    addCandidate(input) {
+        this.add({ subjectKind: "search_candidate", ...input });
+    }
+    get size() {
+        return this.entries.length;
+    }
+    /** Kopie der gesammelten Eintraege in Einfuegereihenfolge. */
+    toArray() {
+        return [...this.entries];
+    }
+    /** Zaehlung je Grund — dieselbe Form wie `SkipLedgerV1.countsByReason`. */
+    countsByReason() {
+        return summarizeSkipReasons(this.entries);
+    }
+}
+//# sourceMappingURL=ledger.js.map

package/dist/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../src/ledger.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAcnF;;;;;GAKG;AACH,MAAM,OAAO,gBAAgB;IACV,OAAO,GAAwB,EAAE,CAAC;IAE5C,GAAG,CAAC,KAAsB;QAC/B,IAAI,CAAC,OAAO,CAAC,IAAI,CACf,oBAAoB,CAAC;YACnB,KAAK,EAAE,QAAQ;YACf,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,GAAG,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC;YACxE,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;YACzD,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;YAC/D,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;YAC5D,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,KAAK;SACxC,CAAC,CACH,CAAC;IACJ,CAAC;IAED,6DAA6D;IACtD,YAAY,CAAC,KAAmE;QACrF,IAAI,CAAC,GAAG,CAAC,EAAE,WAAW,EAAE,kBAAkB,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED,IAAW,IAAI;QACb,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED,8DAA8D;IACvD,OAAO;QACZ,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;IAED,2EAA2E;IACpE,cAAc;QACnB,OAAO,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5C,CAAC;CACF"}

package/dist/payload.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Lesen und Pruefen des gespeicherten Chunk-Payloads (spec.md §10.3).
+ *
+ * Der `VectorStore`-Port liefert `payload?: Record<string, unknown>` — also
+ * ungetypte Daten aus dem Speicher. Sie hier EINMAL zu pruefen und danach mit
+ * `CodeChunkPayloadV1` weiterzuarbeiten ist der Unterschied zwischen einem
+ * Treffer, dem man ansieht warum er unvollstaendig ist, und einem `undefined`,
+ * das drei Stufen spaeter als leeres Feld auftaucht.
+ *
+ * E4: Ein Punkt mit unbrauchbarem Payload wird NICHT stillschweigend
+ * uebersprungen. `readCodeChunkPayload` liefert den Grund als Text zurueck,
+ * und der Aufrufer schreibt ihn in den Skip-Ledger.
+ */
+import type { CodeChunkPayloadV1, ScoredPointV1 } from "@untangle-code/domain";
+/**
+ * Ergebnis des Payload-Lesens: entweder ein Chunk oder ein benannter Grund.
+ *
+ * `substitutedFields` ist der zweite Teil der Ehrlichkeit (E4): ein Payload
+ * kann LESBAR sein und trotzdem Felder vermissen lassen, die dann durch
+ * dokumentierte Ersatzwerte gefuellt werden. Ohne diese Liste sieht der
+ * Treffer in jedem Feld vollstaendig aus — und genau das ist die stille
+ * Beschoenigung, die E4 verbietet. Die Liste ist nach Codepoints sortiert und
+ * leer, wenn nichts ersetzt wurde.
+ */
+export type PayloadReadResult = {
+    ok: true;
+    payload: CodeChunkPayloadV1;
+    substitutedFields: string[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Prueft einen rohen Payload auf die Felder, die der Abrufkern braucht, und
+ * fuellt fehlende OPTIONALE Felder mit dokumentierten Ersatzwerten:
+ * `repo_label` faellt auf `repo_id` zurueck, `ref_name` auf `ref_id`,
+ * `language` auf `"unknown"`, `parse_quality` auf `"failed"` (nicht auf
+ * `"complete"` — eine unbekannte Parsequalitaet als vollstaendig auszugeben
+ * waere genau die stille Beschoenigung, die BUILD_PLAN E4 verbietet).
+ *
+ * JEDER dieser Ersatzwerte wird in `substitutedFields` genannt. Der Aufrufer
+ * traegt die Liste weiter (`SearchHitV1.incompletePayloadFields`), damit ein
+ * Leser den geratenen Wert vom gespeicherten unterscheiden kann.
+ *
+ * Der BEREICH ist davon ausgenommen: ein fehlendes `end_line` faellt auf
+ * `start_line` zurueck, ein fehlendes `end_byte` auf `start_byte` — nie auf 0,
+ * denn ein `SourceRange` mit `endByte < startByte` ist nicht ungenau, sondern
+ * UNGUELTIG; wer damit eine Datei aufschneidet, bekommt die falsche Stelle.
+ * Ist ein Bereich im gespeicherten Payload selbst ungueltig, wird der Punkt
+ * abgelehnt statt zurechtgebogen.
+ */
+export declare function readCodeChunkPayload(raw: Record<string, unknown> | undefined): PayloadReadResult;
+/**
+ * Ein Kandidat des Abrufkerns: gepruefter Payload plus die Rohsignale, mit
+ * denen ihn der Speicher geliefert hat.
+ */
+export interface SearchCandidate {
+    /** Punkt-ID im Vektorspeicher. */
+    pointId: string;
+    payload: CodeChunkPayloadV1;
+    /**
+     * Der rohe Payload, unveraendert. `CodeChunkPayloadV1` beschreibt die
+     * Pflichtfelder aus spec.md §10.3; Felder, die spec.md §10.4 zusaetzlich
+     * indiziert (etwa `changed_at_epoch_ms`) oder die eine spaetere Generation
+     * hinzufuegt (`generation_id`), gehen dadurch NICHT verloren.
+     */
+    raw: Record<string, unknown>;
+    /** Cosine-Score des dichten Zweigs, sofern der Kandidat dort auftauchte. */
+    denseScore?: number;
+    /** 1-basierter Rang im dichten Zweig. */
+    denseRank?: number;
+    /** Roher BM25-Wert des lexikalischen Zweigs (in diesem Paket berechnet). */
+    lexicalScore?: number;
+    /** 1-basierter Rang im lexikalischen Zweig. */
+    lexicalRank?: number;
+    /** 1-basierter Rang im Zweig der exakten Symbolnamen-Treffer. */
+    symbolRank?: number;
+    /** Staerke des Symbolnamen-Treffers in [0, 1] (siehe `symbol-match.ts`). */
+    symbolMatchStrength?: number;
+    /** Beleg des Symbolnamen-Treffers, z. B. `symbol_name == "charge"`. */
+    symbolMatchEvidence?: string;
+    /**
+     * Payload-Felder, die im Speicher fehlten und durch Ersatzwerte gefuellt
+     * wurden (siehe {@link PayloadReadResult}). Leer heisst „nichts ersetzt".
+     */
+    substitutedFields: string[];
+}
+/** Baut aus einem Speicherpunkt einen Kandidaten oder nennt den Grund. */
+export declare function candidateFromPoint(point: ScoredPointV1): {
+    ok: true;
+    candidate: SearchCandidate;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Liest ein zusaetzliches Zahlenfeld aus dem rohen Payload (z. B. `changed_at_epoch_ms`). */
+export declare function readRawNumber(raw: Record<string, unknown>, key: string): number | undefined;
+/** Liest ein zusaetzliches Textfeld aus dem rohen Payload (z. B. `generation_id`). */
+export declare function readRawString(raw: Record<string, unknown>, key: string): string | undefined;
+/**
+ * Der Text, gegen den der lexikalische Zweig rankt. Bewusst mehr als nur der
+ * Inhalt: Pfad und Symbolnamen gehoeren zum Suchgegenstand, sonst findet
+ * „PaymentService charge" den Treffer nur, wenn beide Woerter zufaellig im
+ * Rumpf stehen (spec.md §8.6 nennt fuer den BM25-Text genau diese Bestand-
+ * teile: Code, Pfad, Symbolnamen, Bezeichner).
+ */
+export declare function lexicalDocumentText(payload: CodeChunkPayloadV1): string;
+//# sourceMappingURL=payload.d.ts.map

package/dist/payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../src/payload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAgB,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAiB7F;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,kBAAkB,CAAC;IAAC,iBAAiB,EAAE,MAAM,EAAE,CAAA;CAAE,GACtE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAYlC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,iBAAiB,CA8FhG;AAmID;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,kBAAkB,CAAC;IAC5B;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,uEAAuE;IACvE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,aAAa,GACnB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,eAAe,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAc1E;AAED,8FAA8F;AAC9F,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG3F;AAED,sFAAsF;AACtF,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG3F;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CASvE"}

package/dist/payload.js

@@ -0,0 +1,263 @@
+import { sortByCodepoints } from "@untangle-code/domain";
+/** Pflichtfelder, ohne die ein Treffer keine belastbare Provenienz hat. */
+const REQUIRED_STRING_FIELDS = [
+    "point_type",
+    "workspace_id",
+    "repo_id",
+    "ref_id",
+    "file_id",
+    "file_path",
+    "chunk_id",
+    "metrics_scope_id",
+];
+const PARSE_QUALITIES = ["complete", "partial", "failed"];
+function readString(record, key) {
+    const value = record[key];
+    return typeof value === "string" ? value : undefined;
+}
+function readNumber(record, key) {
+    const value = record[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/**
+ * Prueft einen rohen Payload auf die Felder, die der Abrufkern braucht, und
+ * fuellt fehlende OPTIONALE Felder mit dokumentierten Ersatzwerten:
+ * `repo_label` faellt auf `repo_id` zurueck, `ref_name` auf `ref_id`,
+ * `language` auf `"unknown"`, `parse_quality` auf `"failed"` (nicht auf
+ * `"complete"` — eine unbekannte Parsequalitaet als vollstaendig auszugeben
+ * waere genau die stille Beschoenigung, die BUILD_PLAN E4 verbietet).
+ *
+ * JEDER dieser Ersatzwerte wird in `substitutedFields` genannt. Der Aufrufer
+ * traegt die Liste weiter (`SearchHitV1.incompletePayloadFields`), damit ein
+ * Leser den geratenen Wert vom gespeicherten unterscheiden kann.
+ *
+ * Der BEREICH ist davon ausgenommen: ein fehlendes `end_line` faellt auf
+ * `start_line` zurueck, ein fehlendes `end_byte` auf `start_byte` — nie auf 0,
+ * denn ein `SourceRange` mit `endByte < startByte` ist nicht ungenau, sondern
+ * UNGUELTIG; wer damit eine Datei aufschneidet, bekommt die falsche Stelle.
+ * Ist ein Bereich im gespeicherten Payload selbst ungueltig, wird der Punkt
+ * abgelehnt statt zurechtgebogen.
+ */
+export function readCodeChunkPayload(raw) {
+    if (raw === undefined) {
+        return { ok: false, reason: "point carries no payload (query ran with withPayload=false?)" };
+    }
+    const missing = REQUIRED_STRING_FIELDS.filter((field) => readString(raw, field) === undefined);
+    if (missing.length > 0) {
+        return { ok: false, reason: `payload is missing required field(s): ${missing.join(", ")}` };
+    }
+    const pointType = readString(raw, "point_type");
+    if (pointType !== "code_chunk") {
+        return { ok: false, reason: `payload point_type is "${pointType}", expected "code_chunk"` };
+    }
+    const substituted = [];
+    const parseQualityRaw = readString(raw, "parse_quality");
+    const parseQuality = PARSE_QUALITIES.includes(parseQualityRaw)
+        ? parseQualityRaw
+        : "failed";
+    if (parseQualityRaw === undefined || parseQuality !== parseQualityRaw) {
+        substituted.push("parse_quality");
+    }
+    const repoId = readString(raw, "repo_id");
+    const refId = readString(raw, "ref_id");
+    const range = readSourceRange(raw, substituted);
+    if (!range.ok) {
+        return { ok: false, reason: range.reason };
+    }
+    const { startLine, endLine, startByte, endByte } = range;
+    // Pflichtfelder zuerst, Optionale danach EINZELN zuweisen: eine Kette aus
+    // bedingten Spreads erzeugt unter `exactOptionalPropertyTypes` einen
+    // Uniontyp, den der Compiler ab etwa einem Dutzend Feldern nicht mehr
+    // darstellen kann (TS2590). Die Zuweisungsform ist ausserdem leichter zu
+    // lesen und laesst keinen Zweifel, welches Feld optional ist.
+    const payload = {
+        schema_version: 1,
+        point_type: "code_chunk",
+        workspace_id: readString(raw, "workspace_id"),
+        repo_id: repoId,
+        repo_label: stringOrSubstitute(raw, "repo_label", repoId, substituted),
+        ref_id: refId,
+        ref_name: stringOrSubstitute(raw, "ref_name", refId, substituted),
+        file_id: readString(raw, "file_id"),
+        file_path: readString(raw, "file_path"),
+        file_hash: stringOrSubstitute(raw, "file_hash", "", substituted),
+        language: stringOrSubstitute(raw, "language", "unknown", substituted),
+        parse_quality: parseQuality,
+        chunk_id: readString(raw, "chunk_id"),
+        chunk_kind: stringOrSubstitute(raw, "chunk_kind", "fallback_lines", substituted),
+        chunk_ordinal: numberOrSubstitute(raw, "chunk_ordinal", 0, substituted),
+        start_line: startLine,
+        end_line: endLine,
+        start_byte: startByte,
+        end_byte: endByte,
+        content: stringOrSubstitute(raw, "content", "", substituted),
+        content_hash: stringOrSubstitute(raw, "content_hash", "", substituted),
+        parser_version: stringOrSubstitute(raw, "parser_version", "", substituted),
+        chunker_version: stringOrSubstitute(raw, "chunker_version", "", substituted),
+        metrics_version: stringOrSubstitute(raw, "metrics_version", "unknown", substituted),
+        embedding_profile_id: stringOrSubstitute(raw, "embedding_profile_id", "", substituted),
+        // Altindizes bleiben lesbar, aber der Ersatz steht sichtbar im
+        // Unvollstaendigkeitsledger. Fuer die echte Trefferprovenienz liest der
+        // Abrufkern weiterhin das unveraenderte `raw`-Objekt; "unknown" wird
+        // dadurch nie als gespeicherte Generation ausgegeben.
+        generation_id: stringOrSubstitute(raw, "generation_id", "unknown", substituted),
+        embedding_truncated: raw["embedding_truncated"] === true,
+        metrics_scope: stringOrSubstitute(raw, "metrics_scope", "chunk", substituted),
+        metrics_scope_id: readString(raw, "metrics_scope_id"),
+    };
+    assignOptionalString(payload, "commit_sha", readString(raw, "commit_sha"));
+    assignOptionalString(payload, "symbol_id", readString(raw, "symbol_id"));
+    assignOptionalString(payload, "symbol_name", readString(raw, "symbol_name"));
+    assignOptionalString(payload, "symbol_fqn", readString(raw, "symbol_fqn"));
+    assignOptionalString(payload, "symbol_kind", readString(raw, "symbol_kind"));
+    assignOptionalString(payload, "signature", readString(raw, "signature"));
+    assignOptionalString(payload, "ast_hash", readString(raw, "ast_hash"));
+    assignOptionalNumber(payload, "fragment_index", readNumber(raw, "fragment_index"));
+    assignOptionalNumber(payload, "fragment_count", readNumber(raw, "fragment_count"));
+    assignOptionalNumber(payload, "cyclomatic_classic", readNumber(raw, "cyclomatic_classic"));
+    assignOptionalNumber(payload, "cyclomatic_extended", readNumber(raw, "cyclomatic_extended"));
+    assignOptionalNumber(payload, "cognitive", readNumber(raw, "cognitive"));
+    assignOptionalNumber(payload, "max_nesting", readNumber(raw, "max_nesting"));
+    assignOptionalNumber(payload, "sloc", readNumber(raw, "sloc"));
+    assignOptionalNumber(payload, "halstead_volume", readNumber(raw, "halstead_volume"));
+    assignOptionalNumber(payload, "maintainability_index", readNumber(raw, "maintainability_index"));
+    assignOptionalNumber(payload, "risk_score", readNumber(raw, "risk_score"));
+    return { ok: true, payload, substitutedFields: sortByCodepoints(substituted) };
+}
+/**
+ * Liest den Quellbereich und lehnt einen ungueltigen ab.
+ *
+ * Fehlende Enden werden auf den ANFANG gesetzt (leerer, aber gueltiger
+ * Bereich) und gemeldet; ein gespeichertes Ende VOR dem Anfang ist dagegen
+ * kaputte Provenienz und wird nicht stillschweigend repariert.
+ */
+function readSourceRange(raw, substituted) {
+    const startLine = numberOrSubstitute(raw, "start_line", 1, substituted);
+    const startByte = numberOrSubstitute(raw, "start_byte", 0, substituted);
+    const endLine = numberOrSubstitute(raw, "end_line", startLine, substituted);
+    const endByte = numberOrSubstitute(raw, "end_byte", startByte, substituted);
+    // WP-191: „nicht ganzzahlig" und „liegt vor dem Anfang" sind ZWEI Befunde,
+    // und der Ledger nennt den, der wirklich zutrifft. Zusammengefasst meldete
+    // ein `end_line` von 12.5 bei `start_line` 3 „12.5 is before start_line 3" —
+    // eine Begruendung, die der Zahl offen widerspricht. Wer so etwas liest,
+    // sucht den Fehler an der falschen Stelle, und genau dafuer ist ein Ledger
+    // nicht da.
+    if (!Number.isInteger(startLine)) {
+        return {
+            ok: false,
+            reason: `payload has a non-integer start_line (${startLine}); line numbers are whole numbers`,
+        };
+    }
+    if (startLine < 1) {
+        return {
+            ok: false,
+            reason: `payload has an invalid start_line (${startLine}); lines are 1-based`,
+        };
+    }
+    if (!Number.isInteger(startByte)) {
+        return {
+            ok: false,
+            reason: `payload has a non-integer start_byte (${startByte}); byte offsets are whole numbers`,
+        };
+    }
+    if (startByte < 0) {
+        return { ok: false, reason: `payload has an invalid start_byte (${startByte})` };
+    }
+    if (!Number.isInteger(endLine)) {
+        return {
+            ok: false,
+            reason: `payload has a non-integer end_line (${endLine}); line numbers are whole numbers`,
+        };
+    }
+    if (endLine < startLine) {
+        return {
+            ok: false,
+            reason: `payload has an invalid source range: end_line ${endLine} is before start_line ${startLine}`,
+        };
+    }
+    if (!Number.isInteger(endByte)) {
+        return {
+            ok: false,
+            reason: `payload has a non-integer end_byte (${endByte}); byte offsets are whole numbers`,
+        };
+    }
+    if (endByte < startByte) {
+        return {
+            ok: false,
+            reason: `payload has an invalid source range: end_byte ${endByte} is before start_byte ${startByte}`,
+        };
+    }
+    return { ok: true, startLine, endLine, startByte, endByte };
+}
+/** Liest ein Textfeld oder nennt den Ersatzwert beim Namen. */
+function stringOrSubstitute(raw, key, fallback, substituted) {
+    const value = readString(raw, key);
+    if (value === undefined) {
+        substituted.push(key);
+        return fallback;
+    }
+    return value;
+}
+/** Liest ein Zahlenfeld oder nennt den Ersatzwert beim Namen. */
+function numberOrSubstitute(raw, key, fallback, substituted) {
+    const value = readNumber(raw, key);
+    if (value === undefined) {
+        substituted.push(key);
+        return fallback;
+    }
+    return value;
+}
+function assignOptionalString(payload, key, value) {
+    if (value !== undefined) {
+        payload[key] = value;
+    }
+}
+function assignOptionalNumber(payload, key, value) {
+    if (value !== undefined) {
+        payload[key] = value;
+    }
+}
+/** Baut aus einem Speicherpunkt einen Kandidaten oder nennt den Grund. */
+export function candidateFromPoint(point) {
+    const read = readCodeChunkPayload(point.payload);
+    if (!read.ok) {
+        return { ok: false, reason: read.reason };
+    }
+    return {
+        ok: true,
+        candidate: {
+            pointId: point.id,
+            payload: read.payload,
+            raw: point.payload ?? {},
+            substitutedFields: read.substitutedFields,
+        },
+    };
+}
+/** Liest ein zusaetzliches Zahlenfeld aus dem rohen Payload (z. B. `changed_at_epoch_ms`). */
+export function readRawNumber(raw, key) {
+    const value = raw[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/** Liest ein zusaetzliches Textfeld aus dem rohen Payload (z. B. `generation_id`). */
+export function readRawString(raw, key) {
+    const value = raw[key];
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
+/**
+ * Der Text, gegen den der lexikalische Zweig rankt. Bewusst mehr als nur der
+ * Inhalt: Pfad und Symbolnamen gehoeren zum Suchgegenstand, sonst findet
+ * „PaymentService charge" den Treffer nur, wenn beide Woerter zufaellig im
+ * Rumpf stehen (spec.md §8.6 nennt fuer den BM25-Text genau diese Bestand-
+ * teile: Code, Pfad, Symbolnamen, Bezeichner).
+ */
+export function lexicalDocumentText(payload) {
+    const parts = [
+        payload.file_path,
+        payload.symbol_name ?? "",
+        payload.symbol_fqn ?? "",
+        payload.signature ?? "",
+        payload.content,
+    ];
+    return parts.filter((part) => part !== "").join("\n");
+}
+//# sourceMappingURL=payload.js.map

package/dist/payload.js.map

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

package/dist/port.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Der Port des Abrufkerns.
+ *
+ * Er ist bewusst so geschnitten, dass er OHNE laufendes Qdrant vollstaendig
+ * testbar ist: alles, was Infrastruktur braucht, steckt hinter zwei bereits
+ * bestehenden Domain-Ports (`VectorStore`, `EmbeddingProvider`) plus einer
+ * kleinen, injizierbaren Funktion fuer die spaerliche Vektorisierung. Die
+ * Kontraktsuite in `testing/search-port.contract.ts` laeuft deshalb unveraendert
+ * gegen den In-Memory-Speicher des testkits und spaeter gegen den echten
+ * Qdrant-Adapter — dieselbe Bauart wie `runVectorStoreContract`.
+ *
+ * Ausdruecklich NICHT Teil des Ports: Collection-Namen. Welche Collection zu
+ * welchem Embedding-Profil gehoert, entscheidet der Adapter (spec.md §10.1);
+ * der Abrufkern bekommt die fertige Zuordnung als {@link ProfileTargetV1}
+ * gereicht. Damit kennt dieses Paket kein Qdrant-Detail.
+ */
+import type { EmbeddingProvider, FindabilitySummaryV1, PortCallOptions, SearchGraphRelationsV1, SearchResultSetV1, SparseVectorV1, ToolWarningV1 } from "@untangle-code/domain";
+import type { GrepRequestV1, GrepResultSetV1, UntangleSearchRequestV1 } from "./types.js";
+/**
+ * Ein Suchziel: genau ein Embedding-Profil, genau eine Collection, die
+ * Repositories, die darin liegen.
+ *
+ * Mehrere Ziele heissen mehrere Ergebnisgruppen (spec.md §13.4): Scores
+ * verschiedener Profile werden NIE in eine gemeinsame absolute Rangfolge
+ * gemischt.
+ */
+export interface ProfileTargetV1 {
+    embeddingProfileId: string;
+    /** Name der Collection im Vektorspeicher. */
+    collection: string;
+    /** Repositories, die zu dieser Collection beitragen. */
+    repoIds: string[];
+    /** Der Embedder dieses Profils; erzeugt das Query-Embedding. */
+    embedder: EmbeddingProvider;
+    /** Lokal bekannte Generationen je Repo/Ref samt Abschlussstatus als Provenienz. */
+    indexContexts?: readonly {
+        repoId: string;
+        refId: string;
+        generationId: string;
+        /** Immutable manifest fingerprint for this completed corpus snapshot. */
+        corpusRevisionFingerprint?: string;
+        outcome: "running" | "completed" | "cancelled" | "failed";
+    }[];
+}
+/**
+ * Erzeugt den spaerlichen Vektor einer Anfrage fuer den Abruf im Speicher.
+ *
+ * Die Funktion MUSS dieselbe Tokenisierung und Hashbildung verwenden wie der
+ * Indexlauf, sonst treffen Anfrage- und Dokumentvektor sich nicht. Genau
+ * deshalb ist sie injiziert und nicht hier implementiert: sie gehoert zum
+ * Speicheradapter, nicht zum Abrufkern.
+ *
+ * Fehlt sie, ist der lexikalische Abrufzweig nicht ausfuehrbar. Hybrid kann
+ * ueber Dense und Symbolnamen sichtbar degradiert antworten; reine
+ * lexikalische Suche meldet einen Fehler. Der BM25-Rang wird weiterhin in
+ * diesem Paket berechnet (`bm25.ts`).
+ */
+export type SparseVectorizer = (text: string) => SparseVectorV1;
+/** Liefert die Findability eines Symbols, sofern sie berechnet wurde. */
+export type FindabilityLookup = (symbolId: string) => FindabilitySummaryV1 | undefined;
+/** Liefert die Graph-Naehe eines Symbols zur Anfrage, in [0, 1]. */
+export type GraphProximityLookup = (symbolId: string) => number | undefined;
+/** Ein bereits final gerankter Treffer, den ein Graphadapter anreichern darf. */
+export interface SearchGraphEnrichmentTargetV1 {
+    /** Nur innerhalb eines Aufrufs eindeutig; wird unveraendert zurueckgegeben. */
+    targetId: string;
+    workspaceId: string;
+    generationId: string;
+    repoId: string;
+    refId: string;
+    fileId: string;
+    filePath: string;
+    symbolId?: string;
+}
+/** Batch-Anfrage an den optionalen, graph-agnostischen Anreicherungsport. */
+export interface SearchGraphEnrichmentRequestV1 {
+    includeContext: boolean;
+    includeLinked: boolean;
+    /** Harte Obergrenze je Treffer und Graphart. */
+    relationLimit: number;
+    /** Reihenfolge entspricht Gruppenreihenfolge und finalem Rang. */
+    targets: readonly SearchGraphEnrichmentTargetV1[];
+}
+/** Anreicherung genau eines finalen Treffers. */
+export interface SearchGraphEnrichmentEntryV1 {
+    targetId: string;
+    graphContext?: SearchGraphRelationsV1;
+    linkedSymbols?: SearchGraphRelationsV1;
+}
+/** Batch-Ergebnis; Teilgraph-Ausfaelle bleiben als Warnungen und Facetten sichtbar. */
+export interface SearchGraphEnrichmentResultV1 {
+    entries: readonly SearchGraphEnrichmentEntryV1[];
+    warnings: readonly ToolWarningV1[];
+}
+/**
+ * Schmale Grenze zum persistierten File-/Symbolgraphen. Das Search-Paket
+ * kennt weder deren Snapshottypen noch deren Speicherlayout.
+ */
+export interface SearchGraphEnrichmentPort {
+    enrich(request: SearchGraphEnrichmentRequestV1, options?: PortCallOptions): Promise<SearchGraphEnrichmentResultV1>;
+}
+/**
+ * Der Abrufkern als Port: semantische Suche und grep-artige Suche unter EINER
+ * Oberflaeche (Nutzerwunsch A4).
+ */
+export interface SearchPort {
+    /** Hybride Suche mit vollstaendiger Score-Zerlegung (spec.md §13). */
+    search(request: UntangleSearchRequestV1, options?: PortCallOptions): Promise<SearchResultSetV1>;
+    /** Regex-/Literalsuche ueber den indexierten Inhalt. */
+    grep(request: GrepRequestV1, options?: PortCallOptions): Promise<GrepResultSetV1>;
+}
+//# sourceMappingURL=port.d.ts.map

package/dist/port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.d.ts","sourceRoot":"","sources":["../src/port.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EACV,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,sBAAsB,EACtB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACd,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1F;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,gEAAgE;IAChE,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,mFAAmF;IACnF,aAAa,CAAC,EAAE,SAAS;QACvB,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE,MAAM,CAAC;QACrB,yEAAyE;QACzE,yBAAyB,CAAC,EAAE,MAAM,CAAC;QACnC,OAAO,EAAE,SAAS,GAAG,WAAW,GAAG,WAAW,GAAG,QAAQ,CAAC;KAC3D,EAAE,CAAC;CACL;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,cAAc,CAAC;AAEhE,yEAAyE;AACzE,MAAM,MAAM,iBAAiB,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,oBAAoB,GAAG,SAAS,CAAC;AAEvF,oEAAoE;AACpE,MAAM,MAAM,oBAAoB,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;AAE5E,iFAAiF;AACjF,MAAM,WAAW,6BAA6B;IAC5C,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,6EAA6E;AAC7E,MAAM,WAAW,8BAA8B;IAC7C,cAAc,EAAE,OAAO,CAAC;IACxB,aAAa,EAAE,OAAO,CAAC;IACvB,gDAAgD;IAChD,aAAa,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,OAAO,EAAE,SAAS,6BAA6B,EAAE,CAAC;CACnD;AAED,iDAAiD;AACjD,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,sBAAsB,CAAC;IACtC,aAAa,CAAC,EAAE,sBAAsB,CAAC;CACxC;AAED,uFAAuF;AACvF,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,SAAS,4BAA4B,EAAE,CAAC;IACjD,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC,MAAM,CACJ,OAAO,EAAE,8BAA8B,EACvC,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,6BAA6B,CAAC,CAAC;CAC3C;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,sEAAsE;IACtE,MAAM,CAAC,OAAO,EAAE,uBAAuB,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAChG,wDAAwD;IACxD,IAAI,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CACnF"}

package/dist/port.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=port.js.map

package/dist/port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.js","sourceRoot":"","sources":["../src/port.ts"],"names":[],"mappings":""}

package/dist/product-complexity.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Task-basierte Search Journeys und Dynamic Product Complexity.
+ *
+ * Dieser Reducer ist I/O-agnostisch. Er speichert ausschliesslich ueber den
+ * Domain-Port, liest Zeit/Zufall ueber Ports und berechnet jede Kennzahl aus
+ * den persistierten Beobachtungen neu. Damit kann derselbe Ablauf lokal, im
+ * MCP-Server und in Tests identisch laufen.
+ */
+import { type Clock, type DynamicProductComplexityReportV1, type DynamicSearchComplexityV1, type PortCallOptions, type Random, type SearchJourneyAttemptV1, type SearchJourneyAbandonReasonCode, type SearchJourneyExecutionContextInputV1, type SearchJourneyNavigationKind, type SearchJourneyStorePort, type SearchJourneyTargetV1, type SearchJourneyV1, type SearchResultSetV1 } from "@untangle-code/domain";
+export declare const MINIMUM_PRODUCT_COMPLEXITY_SESSIONS = 3;
+export declare const MAX_SEARCH_JOURNEY_ATTEMPTS = 128;
+export declare const MAX_SEARCH_JOURNEY_FEATURE_ID_LENGTH = 256;
+export declare const MAX_SEARCH_JOURNEY_NAVIGATION_EVENTS = 512;
+interface SearchJourneyServiceBaseDeps {
+    workspaceId: string;
+    store: SearchJourneyStorePort;
+    clock: Clock;
+    random: Random;
+}
+/** Ein stabiler Key oder ein persistenter Provider ist fuer korrekte Wiederaufnahme zwingend. */
+export type SearchJourneyServiceDeps = SearchJourneyServiceBaseDeps & ({
+    fingerprintKey: Uint8Array;
+    fingerprintKeyProvider?: never;
+} | {
+    fingerprintKey?: never;
+    /** Lazy Variante, damit reine Leseoperationen keinen lokalen Schluessel anlegen. */
+    fingerprintKeyProvider: (options?: PortCallOptions) => Promise<Uint8Array>;
+});
+export interface StartSearchJourneyInput {
+    goal: string;
+    /** Stabile, vom Produkt vergebene Kennung fuer feature-uebergreifende Probevergleiche. */
+    featureId?: string;
+    /** Caller labels are pseudonymized by default; no automatic model or task inference. */
+    executionContext?: SearchJourneyExecutionContextInputV1;
+    /** Persistiert Ziel- und Querytext; Default false speichert nur Fingerprints. */
+    retainText?: boolean;
+}
+export interface ObserveSearchJourneyNavigationInput {
+    kind: SearchJourneyNavigationKind;
+    toolName?: string;
+    target?: SearchJourneyTargetV1;
+}
+export interface CompleteSearchJourneyInput {
+    target: SearchJourneyTargetV1;
+    /** Praezisiert den akzeptierten Versuch, wenn derselbe Treffer mehrfach vorkam. */
+    acceptedAttemptId?: string;
+}
+export interface RecordFailedSearchInput {
+    query: string;
+    failureCode: string;
+    failureReason: string;
+}
+export interface AbandonSearchJourneyInput {
+    /** Kontrollierter Grund, der auch im textfreien Default sicher gespeichert werden kann. */
+    reasonCode?: SearchJourneyAbandonReasonCode;
+    /** Freitext; wird nur bei einer mit `retainText` gestarteten Journey gespeichert. */
+    reason?: string;
+}
+export interface SearchJourneySearchLink {
+    /** 1-basierter, pro Session eindeutiger Schritt. */
+    step?: number;
+}
+export interface RecordedSearchAttempt {
+    session: SearchJourneyV1;
+    attempt: SearchJourneyAttemptV1;
+}
+/** Berechnet die erklaerbaren Komponenten einer abgeschlossenen Journey. */
+export declare function assessSearchJourney(session: SearchJourneyV1, input: CompleteSearchJourneyInput): DynamicSearchComplexityV1;
+/** Aggregiert ausschliesslich kompatible Messkontexte in getrennten Kohorten. */
+export declare function buildDynamicProductComplexityReport(workspaceId: string, sessions: readonly SearchJourneyV1[], generatedAt: string): DynamicProductComplexityReportV1;
+export declare class SearchJourneyService {
+    private readonly deps;
+    private readonly pendingMutations;
+    private fingerprintKey;
+    constructor(deps: SearchJourneyServiceDeps);
+    start(input: StartSearchJourneyInput, options?: PortCallOptions): Promise<SearchJourneyV1>;
+    get(sessionId: string, options?: PortCallOptions): Promise<SearchJourneyV1>;
+    recordSearch(sessionId: string, result: SearchResultSetV1, link?: SearchJourneySearchLink, options?: PortCallOptions): Promise<RecordedSearchAttempt>;
+    recordFailedSearch(sessionId: string, input: RecordFailedSearchInput, link?: SearchJourneySearchLink, options?: PortCallOptions): Promise<RecordedSearchAttempt>;
+    observeNavigation(sessionId: string, input: ObserveSearchJourneyNavigationInput, options?: PortCallOptions): Promise<SearchJourneyV1>;
+    complete(sessionId: string, input: CompleteSearchJourneyInput, options?: PortCallOptions): Promise<SearchJourneyV1>;
+    abandon(sessionId: string, input?: AbandonSearchJourneyInput, options?: PortCallOptions): Promise<SearchJourneyV1>;
+    report(options?: PortCallOptions): Promise<DynamicProductComplexityReportV1>;
+    private validatedFingerprintKey;
+    private getFingerprintKey;
+    private mutate;
+}
+export {};
+//# sourceMappingURL=product-complexity.d.ts.map