@cachly-dev/mcp-server 0.10.123 → 0.10.125

package/dist/src/lesson-preview.d.ts

@@ -0,0 +1,81 @@
+/**
+ * lesson-preview — one place that decides how a lesson is shown in a briefing.
+ *
+ * WHY THIS EXISTS (measured 2026-08-16, real incident):
+ * A session briefing showed this lesson line:
+ *
+ *   ✅🔴 `node4:einrichtung-contabo-und-fallen` — node-4 (Contabo, 169.58.175.157,
+ *   Lauterbourg FR, 12 Kerne / 48 GB / 400 GB, 25,29 EUR/Monat) eingeri
+ *
+ * The reader needed one thing from that lesson: the WireGuard address of the
+ * machine. It sits at character 323 of `what_worked`. The preview cut at 100.
+ * Worse, the lesson's `what_failed` field held the literal sentence "always read
+ * `wg show wg0 allowed-ips`" — and no briefing surface renders `what_failed` for
+ * a lesson whose outcome is "success". The lesson was displayed, at the right
+ * moment, and the exact mistake it warns about happened anyway.
+ *
+ * The fix is not "show more prose". The two most actionable fields of that
+ * lesson were already short and structured:
+ *
+ *   commands:   ["wg show wg0 allowed-ips", "ssh -i ~/.ssh/... -p 2222 root@..."]
+ *   file_paths: ["/etc/wireguard/wg0.conf", ...]
+ *
+ * ~15 tokens that answer the question, thrown away in favour of 100 characters
+ * of preamble. So a preview renders three things now: trimmed prose, a facts
+ * tail drawn from the structured fields, and — for critical lessons — the
+ * warning, regardless of outcome.
+ *
+ * This helps the EXISTING corpus. A writing rule ("put the fact first") only
+ * improves lessons written after it; reading structured fields improves every
+ * lesson ever stored.
+ */
+export interface PreviewLesson {
+    topic: string;
+    outcome?: string;
+    severity?: string;
+    what_worked?: string;
+    what_failed?: string;
+    commands?: string[];
+    file_paths?: string[];
+}
+export interface PreviewOptions {
+    /** Prose budget for what_worked. Default 100 — the historical briefing value. */
+    maxChars?: number;
+    /** Render the commands/paths tail. Default true. */
+    facts?: boolean;
+    /** Render the warning line for critical lessons. Default true. */
+    warning?: boolean;
+    /** How many commands + paths to show. Default 2 each. */
+    maxFacts?: number;
+    /** Per-fact character cap. Default 64. */
+    factChars?: number;
+    /** Character cap for the warning line. Default 110. */
+    warningChars?: number;
+    /** Indent for continuation lines. Default 5 spaces (matches briefing lists). */
+    indent?: string;
+}
+/**
+ * Cut to `max` characters, preferring a word boundary, and mark the cut.
+ * The marker matters: without it a truncated line reads like a complete one,
+ * and the reader never learns there is more to fetch.
+ */
+export declare function trimTo(text: string, max: number): string;
+/**
+ * Facts worth showing even when the prose is cut: commands first (they are
+ * directly runnable), then file paths. Deduplicated, order preserved.
+ */
+export declare function factsOf(l: PreviewLesson, maxFacts: number, factChars: number): string[];
+/**
+ * The warning is the single most fear-inducing, mistake-preventing part of a
+ * lesson — and it was invisible whenever `outcome` was "success". Show it for
+ * critical lessons no matter how the lesson ended.
+ */
+export declare function warningOf(l: PreviewLesson, max: number): string | null;
+/**
+ * Render the body of one briefing entry: prose, then facts, then warning.
+ * Returns lines WITHOUT the caller's bullet/emoji prefix — the caller owns the
+ * first line's prefix, this owns everything after the em dash.
+ */
+export declare function lessonPreviewLines(l: PreviewLesson, opts?: PreviewOptions): string[];
+/** Convenience: the same content as a single newline-joined string. */
+export declare function lessonPreview(l: PreviewLesson, opts?: PreviewOptions): string;

package/dist/src/lesson-preview.js

@@ -0,0 +1,133 @@
+/**
+ * lesson-preview — one place that decides how a lesson is shown in a briefing.
+ *
+ * WHY THIS EXISTS (measured 2026-08-16, real incident):
+ * A session briefing showed this lesson line:
+ *
+ *   ✅🔴 `node4:einrichtung-contabo-und-fallen` — node-4 (Contabo, 169.58.175.157,
+ *   Lauterbourg FR, 12 Kerne / 48 GB / 400 GB, 25,29 EUR/Monat) eingeri
+ *
+ * The reader needed one thing from that lesson: the WireGuard address of the
+ * machine. It sits at character 323 of `what_worked`. The preview cut at 100.
+ * Worse, the lesson's `what_failed` field held the literal sentence "always read
+ * `wg show wg0 allowed-ips`" — and no briefing surface renders `what_failed` for
+ * a lesson whose outcome is "success". The lesson was displayed, at the right
+ * moment, and the exact mistake it warns about happened anyway.
+ *
+ * The fix is not "show more prose". The two most actionable fields of that
+ * lesson were already short and structured:
+ *
+ *   commands:   ["wg show wg0 allowed-ips", "ssh -i ~/.ssh/... -p 2222 root@..."]
+ *   file_paths: ["/etc/wireguard/wg0.conf", ...]
+ *
+ * ~15 tokens that answer the question, thrown away in favour of 100 characters
+ * of preamble. So a preview renders three things now: trimmed prose, a facts
+ * tail drawn from the structured fields, and — for critical lessons — the
+ * warning, regardless of outcome.
+ *
+ * This helps the EXISTING corpus. A writing rule ("put the fact first") only
+ * improves lessons written after it; reading structured fields improves every
+ * lesson ever stored.
+ */
+const DEFAULTS = {
+    maxChars: 100,
+    facts: true,
+    warning: true,
+    maxFacts: 2,
+    factChars: 64,
+    warningChars: 110,
+    indent: '     ',
+};
+/** Collapse whitespace so a multi-line field cannot break list layout. */
+function flat(s) {
+    return String(s ?? '').replace(/\s+/g, ' ').trim();
+}
+/**
+ * Cut to `max` characters, preferring a word boundary, and mark the cut.
+ * The marker matters: without it a truncated line reads like a complete one,
+ * and the reader never learns there is more to fetch.
+ */
+export function trimTo(text, max) {
+    const s = flat(text);
+    if (max <= 0)
+        return '';
+    if (s.length <= max)
+        return s;
+    const hard = s.slice(0, max);
+    const space = hard.lastIndexOf(' ');
+    // Only honour the word boundary if it does not throw away most of the budget.
+    const body = space > max * 0.6 ? hard.slice(0, space) : hard;
+    return `${body.replace(/[\s,;:.-]+$/, '')}…`;
+}
+/**
+ * Facts worth showing even when the prose is cut: commands first (they are
+ * directly runnable), then file paths. Deduplicated, order preserved.
+ */
+export function factsOf(l, maxFacts, factChars) {
+    const out = [];
+    const seen = new Set();
+    const take = (raw, prefix, limit) => {
+        let n = 0;
+        for (const item of Array.isArray(raw) ? raw : []) {
+            if (n >= limit)
+                break;
+            const v = flat(item);
+            if (!v)
+                continue;
+            const key = `${prefix}${v}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push(`${prefix}${trimTo(v, factChars)}`);
+            n++;
+        }
+    };
+    take(l.commands, '⌘ ', maxFacts);
+    take(l.file_paths, '▸ ', maxFacts);
+    return out;
+}
+/**
+ * The warning is the single most fear-inducing, mistake-preventing part of a
+ * lesson — and it was invisible whenever `outcome` was "success". Show it for
+ * critical lessons no matter how the lesson ended.
+ */
+export function warningOf(l, max) {
+    const w = flat(l.what_failed);
+    if (!w)
+        return null;
+    const isCritical = String(l.severity ?? '').toLowerCase() === 'critical';
+    const failed = l.outcome === 'failure' || l.outcome === 'partial';
+    if (!isCritical && !failed)
+        return null;
+    return trimTo(w, max);
+}
+/**
+ * Render the body of one briefing entry: prose, then facts, then warning.
+ * Returns lines WITHOUT the caller's bullet/emoji prefix — the caller owns the
+ * first line's prefix, this owns everything after the em dash.
+ */
+export function lessonPreviewLines(l, opts = {}) {
+    const o = { ...DEFAULTS, ...opts };
+    const lines = [];
+    const prose = trimTo(l.what_worked ?? '', o.maxChars);
+    if (prose)
+        lines.push(prose);
+    if (o.warning) {
+        const w = warningOf(l, o.warningChars);
+        if (w)
+            lines.push(`${o.indent}⚠️ ${w}`);
+    }
+    if (o.facts) {
+        const f = factsOf(l, o.maxFacts, o.factChars);
+        // One line, not one per fact: a briefing lists many lessons, and a
+        // four-line block per lesson would push the interesting ones off screen.
+        if (f.length)
+            lines.push(`${o.indent}${f.join('  ')}`);
+    }
+    return lines;
+}
+/** Convenience: the same content as a single newline-joined string. */
+export function lessonPreview(l, opts = {}) {
+    return lessonPreviewLines(l, opts).join('\n');
+}
+//# sourceMappingURL=lesson-preview.js.map

package/dist/src/lesson-preview.js.map

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

package/dist/src/rangfolge.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Der zusammengesetzte Sortierer.
+ *
+ * ── Was hier drinsteckt, und was NICHT ──────────────────────────────────────
+ *
+ * Am 19.08.2026 wurden an 499 echten Lektionen mit 100 Fragen ein Dutzend
+ * Verfahren durchgemessen. Die meisten haben nichts gebracht. Sie stehen hier,
+ * damit sie niemand ein zweites Mal baut:
+ *
+ *   Symptom-Sicht (what_failed als eigener Vektor)   17 % statt 40 % — das Feld
+ *     beschreibt bei uns nicht das Symptom, sondern was vergeblich versucht wurde
+ *   Schwerpunkt abziehen                             41 % — im Rauschen
+ *   Hauptrichtungen entfernen (1, 3, 6 Stueck)       37–41 % — im Rauschen
+ *   Nabenabzug (CSLS-artig)                          41 % — im Rauschen
+ *   Text in Stuecke schneiden                        nicht gebaut: gemessen deckt
+ *     das beste Stueck genauso viel ab wie der ganze Text (Verhaeltnis 1,00),
+ *     und es liegt bei 86 von 96 Fragen ohnehin am Anfang
+ *
+ * Was BLEIBT, sind vier Bestandteile — kreuzweise geprueft, also auf der einen
+ * Haelfte der Fragen eingestellt und auf der anderen gemessen, in beide
+ * Richtungen:
+ *
+ *                        P@1     MRR
+ *   nur Bedeutung        40 %   51,3 %
+ *   zusammengesetzt      51 %   57,0 %
+ *
+ * ── Die vier Bestandteile ───────────────────────────────────────────────────
+ *
+ * 1. NAEHE ZUM GANZEN TEXT (Sicht A). Der Grundstock.
+ *
+ * 2. NAEHE ZUM THEMENNAMEN (Sicht C). Der Name ist kurz wie eine Frage — der
+ *    Vergleich ist damit symmetrisch, waehrend eine 60-Zeichen-Frage gegen
+ *    1376 Zeichen Text es nicht ist. Allein liefert diese Sicht nur 26 %, im
+ *    Verbund traegt sie verlaesslich (Gewicht 0,6 in beiden Richtungen).
+ *
+ * 3. RUECKKOPPLUNG. Die ersten drei Treffer sind meistens ungefaehr richtig.
+ *    Ihre Vektoren werden zu einem Viertel unter die Frage gemischt, dann wird
+ *    erneut verglichen. Kostet nichts — keine neue Einbettung, nur eine
+ *    Mittelung vorhandener Zahlen.
+ *
+ * 4. SELTENHEITS-UEBERLAPPUNG. Welcher Anteil der SELTENEN Fragewoerter kommt
+ *    im Text vor. Ohne Laengennormierung, ohne unscharfe Treffer, ohne
+ *    Bigramme.
+ *
+ *    Das ist der unbequeme Befund: dieses eine Verhaeltnis bekam beim Einstellen
+ *    das Gewicht 1,0 bis 1,6 — unser ausgefeiltes BM25 mit Laengennormierung,
+ *    Bigramm-Naehe, unscharfen Treffern und Frischebonus bekam NULL. Nicht weil
+ *    Woerter nichts taugen, sondern weil das ganze Beiwerk beim Sortieren
+ *    daneben misst.
+ *
+ * ── Warum innerhalb des Topfes normiert wird ────────────────────────────────
+ *
+ * Ueber den ganzen Bestand liegen alle Aehnlichkeiten zwischen 0,42 und 0,61 —
+ * ein sehr schmales Band, weil alle Vektoren eine gemeinsame Grundrichtung
+ * teilen (gemessen: 69,8 Prozent). Unter fuenfzig Kandidaten spreizt eine
+ * Normierung auf 0 bis 1 genau die Unterschiede auf, um die es geht. Das ist
+ * dasselbe Ziel wie beim Schwerpunkt-Abziehen — nur dort, wo es wirkt.
+ */
+/** Wörter eines Textes, umlautfrei, ohne Kurzwörter. */
+export declare function inhaltsWoerter(text: string): Set<string>;
+/**
+ * Es gibt hier KEINE Stammbildung — und das ist gemessen, nicht vergessen.
+ *
+ * Naheliegend wäre, `Abhaengigkeiten` und `Abhaengigkeit` auf einen Nenner zu
+ * bringen. Drei Varianten wurden am 19.08.2026 an 499 Lektionen mit 100 Fragen
+ * kreuzweise durchgemessen:
+ *
+ *   ohne Stammbildung          P@1 50 %   MRR 56,4 %
+ *   erste 6 Zeichen            P@1 47 %   MRR 54,7 %
+ *   erste 8 Zeichen            P@1 47 %   MRR 54,7 %
+ *
+ * Jede Form von Kürzen kostet drei Punkte. Der Grund liegt daran, was diese
+ * Suche trägt: seltene Fachwörter. `fail2ban`, `stampede`, `timestamptz`,
+ * `keycloak` entscheiden eine Frage praktisch allein — und jede Verschmelzung
+ * verwischt genau sie. `container` und `contains` werden zu demselben Wort,
+ * und aus zwei seltenen wird ein häufiges.
+ *
+ * Beugung einzufangen lohnt sich also nur, wo die häufigen Wörter zählen. Hier
+ * zählen die seltenen.
+ *
+ * (Die Wortform-Behandlung in deutsch.ts bleibt davon unberührt — sie wirkt im
+ * Wortabgleich, der die Vorauswahl macht, nicht in dieser Bewertung.)
+ */
+export declare function grobStamm(w: string): string;
+/**
+ * Die Seltenheit jedes Wortes im Bestand — einmal berechnet, oft benutzt.
+ *
+ * Trifft eine Frage das Wort "nicht", sagt das nichts. Trifft sie "fail2ban",
+ * ist die Sache praktisch entschieden. Ohne diese Gewichtung sind beide gleich
+ * viel wert.
+ */
+export declare class Seltenheit {
+    private df;
+    private anzahl;
+    /** @param texte je ein Text pro Datensatz */
+    constructor(texte: string[]);
+    wert(wort: string): number;
+    /**
+     * Welcher Anteil der seltenen Fragewörter kommt im Text vor.
+     *
+     * Der Nenner ist die Summe über ALLE Fragewörter — ein fehlendes seltenes
+     * Wort zieht damit den Wert herunter. Fehlende Belege zählen also mit, nicht
+     * nur vorhandene.
+     */
+    deckung(frageWoerter: Set<string>, textWoerter: Set<string>): number;
+}
+/** Auf 0 bis 1 spreizen — innerhalb des Topfes, nicht über den Bestand. */
+export declare function spreizeImTopf(werte: number[]): number[];
+/**
+ * Die Frage mit ihren besten Treffern anreichern.
+ *
+ * Die Frage benutzt Alltagsworte, die Lektionen Fachworte. Die ersten Treffer
+ * schlagen diese Brücke: ihre Vektoren zeigen dorthin, wo die Antwort liegt.
+ *
+ * Das Risiko ist bekannt und begrenzt: sind die ersten Treffer falsch, zieht
+ * die Anreicherung in die falsche Richtung. Deshalb bleibt die ursprüngliche
+ * Frage mit drei Vierteln stehen — gemessen war das besser als jede stärkere
+ * Beimischung.
+ */
+export declare function reichereAn(frage: number[], besteTreffer: number[][], anteil?: number): number[];
+/**
+ * Die Gewichte.
+ *
+ * Kreuzweise ermittelt: auf der einen Hälfte der Fragen eingestellt, auf der
+ * anderen gemessen, in beide Richtungen. Die drei Werte hier waren in BEIDEN
+ * Richtungen stabil. Zwei weitere Merkmale — Überlappung mit dem Themennamen
+ * und Qualitätsmerkmale — schwankten zwischen den Richtungen und sind deshalb
+ * NICHT dabei: was nur in einer Hälfte hilft, ist eine Eigenschaft dieser
+ * Hälfte, keine des Verfahrens.
+ */
+export declare const GEWICHTE: {
+    /** Nähe zum ganzen Text. Der Grundstock, deshalb 1. */
+    readonly text: 1;
+    /** Nähe zum Themennamen. In beiden Richtungen 0,6. */
+    readonly thema: 0.6;
+    /** Angereicherte Frage gegen den ganzen Text. In beiden Richtungen 0,3. */
+    readonly rueckkopplung: 0.3;
+    /** Anteil der seltenen Fragewörter im Text. 1,0 bis 1,6 — Mitte genommen. */
+    readonly seltenheit: 1.3;
+};
+export interface Bewertbar {
+    /** Kosinus zur Sicht über den ganzen Text, oder -2 wenn kein Vektor da ist. */
+    naeheText: number;
+    /** Kosinus zur Sicht über den Themennamen. */
+    naeheThema: number;
+    /** Kosinus der angereicherten Frage zum ganzen Text. */
+    naeheRueckkopplung: number;
+    /** Anteil der seltenen Fragewörter, die im Text vorkommen. */
+    seltenheitsDeckung: number;
+}
+/**
+ * Punktzahl je Kandidat. Höher ist besser.
+ *
+ * Erwartet den GANZEN Topf auf einmal, weil die Normierung ihn braucht — eine
+ * Punktzahl für einen einzelnen Kandidaten gibt es nicht und kann es nicht
+ * geben.
+ */
+export declare function bewerteTopf(topf: Bewertbar[], gewichte?: {
+    /** Nähe zum ganzen Text. Der Grundstock, deshalb 1. */
+    readonly text: 1;
+    /** Nähe zum Themennamen. In beiden Richtungen 0,6. */
+    readonly thema: 0.6;
+    /** Angereicherte Frage gegen den ganzen Text. In beiden Richtungen 0,3. */
+    readonly rueckkopplung: 0.3;
+    /** Anteil der seltenen Fragewörter im Text. 1,0 bis 1,6 — Mitte genommen. */
+    readonly seltenheit: 1.3;
+}): number[];
+/** Bequemlichkeit: Kosinus mit Lücken-Behandlung. */
+export declare function naeheOderLuecke(frage: number[] | null, vektor: number[] | null | undefined): number;

package/dist/src/rangfolge.js

@@ -0,0 +1,214 @@
+/**
+ * Der zusammengesetzte Sortierer.
+ *
+ * ── Was hier drinsteckt, und was NICHT ──────────────────────────────────────
+ *
+ * Am 19.08.2026 wurden an 499 echten Lektionen mit 100 Fragen ein Dutzend
+ * Verfahren durchgemessen. Die meisten haben nichts gebracht. Sie stehen hier,
+ * damit sie niemand ein zweites Mal baut:
+ *
+ *   Symptom-Sicht (what_failed als eigener Vektor)   17 % statt 40 % — das Feld
+ *     beschreibt bei uns nicht das Symptom, sondern was vergeblich versucht wurde
+ *   Schwerpunkt abziehen                             41 % — im Rauschen
+ *   Hauptrichtungen entfernen (1, 3, 6 Stueck)       37–41 % — im Rauschen
+ *   Nabenabzug (CSLS-artig)                          41 % — im Rauschen
+ *   Text in Stuecke schneiden                        nicht gebaut: gemessen deckt
+ *     das beste Stueck genauso viel ab wie der ganze Text (Verhaeltnis 1,00),
+ *     und es liegt bei 86 von 96 Fragen ohnehin am Anfang
+ *
+ * Was BLEIBT, sind vier Bestandteile — kreuzweise geprueft, also auf der einen
+ * Haelfte der Fragen eingestellt und auf der anderen gemessen, in beide
+ * Richtungen:
+ *
+ *                        P@1     MRR
+ *   nur Bedeutung        40 %   51,3 %
+ *   zusammengesetzt      51 %   57,0 %
+ *
+ * ── Die vier Bestandteile ───────────────────────────────────────────────────
+ *
+ * 1. NAEHE ZUM GANZEN TEXT (Sicht A). Der Grundstock.
+ *
+ * 2. NAEHE ZUM THEMENNAMEN (Sicht C). Der Name ist kurz wie eine Frage — der
+ *    Vergleich ist damit symmetrisch, waehrend eine 60-Zeichen-Frage gegen
+ *    1376 Zeichen Text es nicht ist. Allein liefert diese Sicht nur 26 %, im
+ *    Verbund traegt sie verlaesslich (Gewicht 0,6 in beiden Richtungen).
+ *
+ * 3. RUECKKOPPLUNG. Die ersten drei Treffer sind meistens ungefaehr richtig.
+ *    Ihre Vektoren werden zu einem Viertel unter die Frage gemischt, dann wird
+ *    erneut verglichen. Kostet nichts — keine neue Einbettung, nur eine
+ *    Mittelung vorhandener Zahlen.
+ *
+ * 4. SELTENHEITS-UEBERLAPPUNG. Welcher Anteil der SELTENEN Fragewoerter kommt
+ *    im Text vor. Ohne Laengennormierung, ohne unscharfe Treffer, ohne
+ *    Bigramme.
+ *
+ *    Das ist der unbequeme Befund: dieses eine Verhaeltnis bekam beim Einstellen
+ *    das Gewicht 1,0 bis 1,6 — unser ausgefeiltes BM25 mit Laengennormierung,
+ *    Bigramm-Naehe, unscharfen Treffern und Frischebonus bekam NULL. Nicht weil
+ *    Woerter nichts taugen, sondern weil das ganze Beiwerk beim Sortieren
+ *    daneben misst.
+ *
+ * ── Warum innerhalb des Topfes normiert wird ────────────────────────────────
+ *
+ * Ueber den ganzen Bestand liegen alle Aehnlichkeiten zwischen 0,42 und 0,61 —
+ * ein sehr schmales Band, weil alle Vektoren eine gemeinsame Grundrichtung
+ * teilen (gemessen: 69,8 Prozent). Unter fuenfzig Kandidaten spreizt eine
+ * Normierung auf 0 bis 1 genau die Unterschiede auf, um die es geht. Das ist
+ * dasselbe Ziel wie beim Schwerpunkt-Abziehen — nur dort, wo es wirkt.
+ */
+import { kosinus } from './bedeutung.js';
+/** Wörter eines Textes, umlautfrei, ohne Kurzwörter. */
+export function inhaltsWoerter(text) {
+    return new Set(text.toLowerCase()
+        .replace(/ä/g, 'ae').replace(/ö/g, 'oe').replace(/ü/g, 'ue').replace(/ß/g, 'ss')
+        .split(/[^a-z0-9]+/)
+        .filter((w) => w.length > 3));
+}
+/**
+ * Es gibt hier KEINE Stammbildung — und das ist gemessen, nicht vergessen.
+ *
+ * Naheliegend wäre, `Abhaengigkeiten` und `Abhaengigkeit` auf einen Nenner zu
+ * bringen. Drei Varianten wurden am 19.08.2026 an 499 Lektionen mit 100 Fragen
+ * kreuzweise durchgemessen:
+ *
+ *   ohne Stammbildung          P@1 50 %   MRR 56,4 %
+ *   erste 6 Zeichen            P@1 47 %   MRR 54,7 %
+ *   erste 8 Zeichen            P@1 47 %   MRR 54,7 %
+ *
+ * Jede Form von Kürzen kostet drei Punkte. Der Grund liegt daran, was diese
+ * Suche trägt: seltene Fachwörter. `fail2ban`, `stampede`, `timestamptz`,
+ * `keycloak` entscheiden eine Frage praktisch allein — und jede Verschmelzung
+ * verwischt genau sie. `container` und `contains` werden zu demselben Wort,
+ * und aus zwei seltenen wird ein häufiges.
+ *
+ * Beugung einzufangen lohnt sich also nur, wo die häufigen Wörter zählen. Hier
+ * zählen die seltenen.
+ *
+ * (Die Wortform-Behandlung in deutsch.ts bleibt davon unberührt — sie wirkt im
+ * Wortabgleich, der die Vorauswahl macht, nicht in dieser Bewertung.)
+ */
+export function grobStamm(w) {
+    return w;
+}
+/**
+ * Die Seltenheit jedes Wortes im Bestand — einmal berechnet, oft benutzt.
+ *
+ * Trifft eine Frage das Wort "nicht", sagt das nichts. Trifft sie "fail2ban",
+ * ist die Sache praktisch entschieden. Ohne diese Gewichtung sind beide gleich
+ * viel wert.
+ */
+export class Seltenheit {
+    df = new Map();
+    anzahl = 0;
+    /** @param texte je ein Text pro Datensatz */
+    constructor(texte) {
+        this.anzahl = texte.length;
+        for (const t of texte) {
+            for (const w of inhaltsWoerter(t))
+                this.df.set(grobStamm(w), (this.df.get(grobStamm(w)) ?? 0) + 1);
+        }
+    }
+    wert(wort) {
+        return Math.log((this.anzahl + 1) / ((this.df.get(grobStamm(wort)) ?? 0) + 1));
+    }
+    /**
+     * Welcher Anteil der seltenen Fragewörter kommt im Text vor.
+     *
+     * Der Nenner ist die Summe über ALLE Fragewörter — ein fehlendes seltenes
+     * Wort zieht damit den Wert herunter. Fehlende Belege zählen also mit, nicht
+     * nur vorhandene.
+     */
+    deckung(frageWoerter, textWoerter) {
+        let gesamt = 0;
+        let getroffen = 0;
+        for (const w of frageWoerter) {
+            const g = this.wert(w);
+            gesamt += g;
+            if (textWoerter.has(grobStamm(w)))
+                getroffen += g;
+        }
+        return gesamt > 0 ? getroffen / gesamt : 0;
+    }
+}
+/** Auf 0 bis 1 spreizen — innerhalb des Topfes, nicht über den Bestand. */
+export function spreizeImTopf(werte) {
+    const gueltig = werte.filter((x) => Number.isFinite(x) && x > -2);
+    if (gueltig.length === 0)
+        return werte.map(() => 0);
+    let min = Infinity;
+    let max = -Infinity;
+    for (const x of gueltig) {
+        if (x < min)
+            min = x;
+        if (x > max)
+            max = x;
+    }
+    if (max === min)
+        return werte.map(() => 0.5);
+    return werte.map((x) => (x > -2 ? (x - min) / (max - min) : 0));
+}
+/**
+ * Die Frage mit ihren besten Treffern anreichern.
+ *
+ * Die Frage benutzt Alltagsworte, die Lektionen Fachworte. Die ersten Treffer
+ * schlagen diese Brücke: ihre Vektoren zeigen dorthin, wo die Antwort liegt.
+ *
+ * Das Risiko ist bekannt und begrenzt: sind die ersten Treffer falsch, zieht
+ * die Anreicherung in die falsche Richtung. Deshalb bleibt die ursprüngliche
+ * Frage mit drei Vierteln stehen — gemessen war das besser als jede stärkere
+ * Beimischung.
+ */
+export function reichereAn(frage, besteTreffer, anteil = 0.25) {
+    if (besteTreffer.length === 0)
+        return frage;
+    const d = frage.length;
+    const m = new Array(d).fill(0);
+    for (const v of besteTreffer) {
+        if (v.length !== d)
+            continue;
+        for (let i = 0; i < d; i++)
+            m[i] += v[i] / besteTreffer.length;
+    }
+    return frage.map((x, i) => (1 - anteil) * x + anteil * m[i]);
+}
+/**
+ * Die Gewichte.
+ *
+ * Kreuzweise ermittelt: auf der einen Hälfte der Fragen eingestellt, auf der
+ * anderen gemessen, in beide Richtungen. Die drei Werte hier waren in BEIDEN
+ * Richtungen stabil. Zwei weitere Merkmale — Überlappung mit dem Themennamen
+ * und Qualitätsmerkmale — schwankten zwischen den Richtungen und sind deshalb
+ * NICHT dabei: was nur in einer Hälfte hilft, ist eine Eigenschaft dieser
+ * Hälfte, keine des Verfahrens.
+ */
+export const GEWICHTE = {
+    /** Nähe zum ganzen Text. Der Grundstock, deshalb 1. */
+    text: 1,
+    /** Nähe zum Themennamen. In beiden Richtungen 0,6. */
+    thema: 0.6,
+    /** Angereicherte Frage gegen den ganzen Text. In beiden Richtungen 0,3. */
+    rueckkopplung: 0.3,
+    /** Anteil der seltenen Fragewörter im Text. 1,0 bis 1,6 — Mitte genommen. */
+    seltenheit: 1.3,
+};
+/**
+ * Punktzahl je Kandidat. Höher ist besser.
+ *
+ * Erwartet den GANZEN Topf auf einmal, weil die Normierung ihn braucht — eine
+ * Punktzahl für einen einzelnen Kandidaten gibt es nicht und kann es nicht
+ * geben.
+ */
+export function bewerteTopf(topf, gewichte = GEWICHTE) {
+    const t = spreizeImTopf(topf.map((k) => k.naeheText));
+    const th = spreizeImTopf(topf.map((k) => k.naeheThema));
+    const r = spreizeImTopf(topf.map((k) => k.naeheRueckkopplung));
+    return topf.map((k, i) => gewichte.text * t[i]
+        + gewichte.thema * th[i]
+        + gewichte.rueckkopplung * r[i]
+        + gewichte.seltenheit * k.seltenheitsDeckung);
+}
+/** Bequemlichkeit: Kosinus mit Lücken-Behandlung. */
+export function naeheOderLuecke(frage, vektor) {
+    return frage && vektor && vektor.length > 0 ? kosinus(frage, vektor) : -2;
+}
+//# sourceMappingURL=rangfolge.js.map

package/dist/src/rangfolge.js.map

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