@cachly-dev/mcp-server 0.10.124 → 0.10.126

package/dist/src/versuch.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Messtechnik fuer den Rueckfall-Versuch (dev.to "rules-before-the-run").
+ *
+ * ── Worum es geht ────────────────────────────────────────────────────────────
+ *
+ * Der Artikel sagt zu: wir messen, ob eine abgerufene Lektion, die WIRKLICH bis
+ * ins Modell kommt, den Rueckfall senkt (dieselbe Lektion muss kein zweites Mal
+ * geschrieben werden). Diese Datei baut nur das Messgeraet. Sie startet nichts.
+ *
+ * Ohne den Schalter `CACHLY_VERSUCH=an` (siehe `versuchStart`) aendert sich am
+ * Verhalten des Recall-Pfads NICHTS — kein Zurueckhalten, kein Schreiben nach
+ * Redis, keine Markierung im Text. Das ist keine Nebenbedingung, das ist der
+ * ganze Zweck: der Versuch soll erst beginnen, wenn Heinrich ihn startet.
+ *
+ * ── Der Kanarienvogel ────────────────────────────────────────────────────────
+ *
+ * Zu pruefen ist nicht, ob eine Lektion ABGERUFEN wurde. Zu pruefen ist, ob ihr
+ * Text VOLLSTAENDIG in der Antwort landet, die das Modell sieht. Anlass: eine
+ * Lektion trug die gesuchte Adresse an Zeichen 323 von `what_worked`, die
+ * Anzeige schnitt bei 100 Zeichen ab (siehe lesson-preview.ts). Die Lektion war
+ * eingeblendet, der Fehler passierte trotzdem — genau der Zustand, den ein
+ * "wurde abgerufen"-Zaehler nie sieht.
+ *
+ * Die Markierung sitzt deshalb am Ende von `what_worked` — dem Feld, an dem der
+ * Anlass hing, und dem Feld, das `lessonPreviewLines` als Erstes und am
+ * grosszuegigsten kuerzt. Sie besteht aus acht Zero-Width-Space-Zeichen
+ * (U+200B): unsichtbar in jedem Renderer (Terminal, Markdown, HTML), und sie
+ * uebersteht sowohl `flat()`s Leerzeichen-Kollaps als auch `String#trim()` —
+ * beide fassen nur "richtige" Leerzeichen an, U+200B gehoert zu keiner der
+ * beiden Kategorien. Acht Wiederholungen, damit ein einzelnes zufaelliges
+ * Zero-Width-Zeichen in echtem Nutzertext die Markierung nicht vortaeuscht.
+ *
+ * WICHTIG: die Markierung wird NICHT roh ans Ende des JSON-Strings gehaengt.
+ * Das wuerde `JSON.parse` in `recallVorschau` brechen und den Fallback-Pfad
+ * (rohes `trimTo` ueber das GANZE JSON-Objekt) erzwingen — einen Pfad, den
+ * echte, unmarkierte Lektionen nie durchlaufen. Das Ergebnis waere ein
+ * Fehlalarm, kein Messwert. Die Markierung wird darum in die geparste
+ * `what_worked`-Zeichenkette eingefuegt, das Objekt bleibt gueltiges JSON, und
+ * der Kanarienvogel durchlaeuft exakt den Pfad, den eine echte Lektion auch
+ * durchlaeuft.
+ *
+ * Geprueft wird am Ende die WIRKLICH zusammengebaute Antwort (`lines.join`),
+ * nicht eine Nebenrechnung — siehe `schliesseVersuchAb`. Die Markierung wird
+ * danach aus dem Text entfernt, bevor er den Nutzer erreicht.
+ */
+import type { Redis } from 'ioredis';
+export declare const VERSUCH_ENV = "CACHLY_VERSUCH";
+export declare const VERSUCH_SALZ_ENV = "CACHLY_VERSUCH_SALZ";
+/** Grund fuer `meldeEinmal`: Versuch eingeschaltet, aber kein Salz gesetzt. */
+export declare const OHNE_SALZ = "versuch-ohne-salz";
+/**
+ * Der einzige Einstiegspunkt fuer die Frage "soll der Versuch jetzt laufen?".
+ *
+ * Gibt das Salz zurueck, wenn ja — sonst `null`. Zwei Faelle enden bei `null`:
+ * der Schalter steht nicht auf "an", oder er steht auf "an", aber das Salz
+ * fehlt. Der zweite Fall meldet sich einmal je Prozess nach stderr (ueber
+ * `meldeEinmal`) und verhaelt sich danach wie der erste — still weiterlaufen
+ * waere die Fehlerklasse, gegen die `aussetzer.ts` gebaut wurde.
+ */
+export declare function versuchStart(): string | null;
+/**
+ * Eine neue, stabile Kennung je Recall-Aufruf.
+ *
+ * Im Recall-Pfad gibt es keine vorhandene Anfrage- oder Turn-Kennung, die man
+ * verlaengern koennte — `requester` ist ein Autorenname, `cachly:session:current`
+ * haelt Zustand je INSTANZ, nicht je Aufruf. Darum: Zeitstempel (sortierbar,
+ * in einer Zeile lesbar) plus vier zufaellige Byte, damit zwei Aufrufe in
+ * derselben Millisekunde nicht kollidieren.
+ */
+export declare function neueKennung(): string;
+export type Zuteilung = 'HOLD' | 'DELIVER';
+/**
+ * Reine Funktion, ohne Netz testbar: Kennung + Salz -> HOLD oder DELIVER.
+ *
+ * Berechnung exakt wie oeffentlich angekuendigt: Kennung und Salz aneinander-
+ * haengen, SHA-256, die ersten VIER Hex-Ziffern als Zahl lesen, modulo 100.
+ * Unter 50 heisst HOLD, sonst DELIVER.
+ */
+export declare function zuteilung(kennung: string, salz: string): Zuteilung;
+/** Ohne einen Treffer ueber dieser Punktzahl gibt es nichts zu messen. */
+export declare const ZULASSUNGS_SCHWELLE = 0;
+/** Gibt es ueberhaupt einen Treffer, der ueber der Schwelle liegt? */
+export declare function istZulassungsfaehig(hoechstePunktzahl: number, schwelle?: number): boolean;
+/** Der Grund, warum eine Anfrage NICHT zulassungsfaehig ist — oder `undefined`. */
+export declare function zulassungsGrund(hoechstePunktzahl: number, schwelle?: number): string | undefined;
+/**
+ * Acht Zero-Width-Spaces. Siehe Dateikopf fuer die Begruendung der Wahl.
+ *
+ * Ueber String.fromCharCode, nicht als roher Unicode-Buchstabe im
+ * Quelltext — ein unsichtbares Zeichen zwischen Anfuehrungszeichen ist beim
+ * Lesen und in `git diff` nicht von "kein Zeichen" zu unterscheiden.
+ */
+export declare const KANARIEN_MARKIERUNG: string;
+/**
+ * Setzt die Kanarien-Markierung ans Ende des `what_worked`-Feldes.
+ *
+ * `inhalt` ist der rohe Redis-Wert, wie ihn `recallVorschau` bekommt — meist
+ * das JSON einer Lektion, manchmal (Kontext-Eintraege, Index) einfacher Text.
+ * Ist es eine Lektion mit `what_worked`, wandert die Markierung dorthin und
+ * das Objekt bleibt gueltiges JSON (Begruendung siehe Dateikopf). Sonst wird
+ * roh ans Ende angehaengt — das ist fuer Nicht-Lektionen korrekt, weil
+ * `recallVorschau` sie ohnehin nur als Rohtext kuerzt.
+ */
+export declare function markiereDatensatz(inhalt: string, markierung?: string): string;
+/**
+ * Ueberlebt die Markierung in der fertig zusammengebauten Antwort?
+ *
+ * Ueberlebt sie: der ganze Datensatz kam durch. Fehlt sie: er wurde gekuerzt.
+ */
+export declare function kanarienUeberlebt(fertigeAntwort: string, markierung?: string): boolean;
+/** Entfernt die Markierung, bevor der Text den Nutzer erreicht. */
+export declare function entferneMarkierung(text: string, markierung?: string): string;
+/** Redis-Schluessel einer Lektion -> ihr Themenname (ohne Praefix). */
+export declare function themaVon(key: string): string;
+/** Hash der Frage — die Frage selbst wird nie gespeichert (Zusage des Artikels). */
+export declare function hashFrage(frage: string): string;
+/** Redis-Schluessel fuer den Protokoll-Eintrag einer Kennung. */
+export declare function turnSchluessel(kennung: string): string;
+export interface VersuchTurnProtokoll {
+    ts: string;
+    frageHash: string;
+    hoechstePunktzahl: number;
+    /** Themenschluessel der zurueckgegebenen (tatsaechlich gezeigten) Lektionen. */
+    themen: string[];
+    zulassungsfaehig: boolean;
+    zulassungsGrund?: string;
+    zuteilung: Zuteilung;
+    /** Nur bei HOLD gesetzt: das Thema, das weggelassen wurde. */
+    weggelassenesThema?: string;
+    kanarienBestanden: boolean;
+}
+/**
+ * Schreibt den Turn-Eintrag. Schlaegt das fehl, wird NICHTS geworfen — der
+ * Nutzer wartet auf eine Antwort, nicht auf ein Protokoll.
+ */
+export declare function schreibeTurnProtokoll(redis: Redis, kennung: string, protokoll: VersuchTurnProtokoll): Promise<void>;
+/** Ein Kandidat aus der schon sortierten Trefferliste von smart_recall. */
+export interface VersuchTreffer {
+    key: string;
+    content: string;
+    punktzahl: number;
+}
+export interface ZuteilungsErgebnis {
+    /** Die neue Trefferliste — bei HOLD fehlt der bisher beste Treffer. */
+    treffer: VersuchTreffer[];
+    zuteilung: Zuteilung;
+    zulassungsfaehig: boolean;
+    zulassungsGrund?: string;
+    /** War DELIVER UND es gab einen Treffer, der die Markierung tragen konnte. */
+    markierungGesetzt: boolean;
+    weggelassenesThema?: string;
+}
+/**
+ * Wendet Zulassung + Zuteilung auf eine Trefferliste an. Reine Funktion,
+ * mutiert `treffer` nicht.
+ *
+ * Ohne zulassungsfaehigen Treffer passiert nichts — Zuteilung wird trotzdem
+ * berechnet und protokolliert, aber es gibt nichts zurueckzuhalten oder zu
+ * markieren. Bei HOLD verschwindet der beste Treffer aus der Liste, die
+ * uebrigen bleiben unveraendert. Bei DELIVER traegt der beste Treffer danach
+ * die Kanarien-Markierung.
+ */
+export declare function wendeZuteilungAn(treffer: readonly VersuchTreffer[], kennung: string, salz: string, hoechstePunktzahl: number, schwelle?: number): ZuteilungsErgebnis;
+export interface VersuchProtokollTeil {
+    frage: string;
+    hoechstePunktzahl: number;
+    themen: string[];
+    zulassungsfaehig: boolean;
+    zulassungsGrund?: string;
+    zuteilung: Zuteilung;
+    weggelassenesThema?: string;
+    markierungGesetzt: boolean;
+}
+/**
+ * Letzter Schritt: prueft den Kanarienvogel gegen die WIRKLICH zusammen-
+ * gebaute Antwort, entfernt die Markierung, schreibt das Protokoll (fire-and-
+ * forget) und gibt den bereinigten Text zurueck — den, den der Nutzer sieht.
+ */
+export declare function schliesseVersuchAb(redis: Redis, kennung: string, teil: VersuchProtokollTeil, fertigeAntwort: string): string;

package/dist/src/versuch.js

@@ -0,0 +1,250 @@
+/**
+ * Messtechnik fuer den Rueckfall-Versuch (dev.to "rules-before-the-run").
+ *
+ * ── Worum es geht ────────────────────────────────────────────────────────────
+ *
+ * Der Artikel sagt zu: wir messen, ob eine abgerufene Lektion, die WIRKLICH bis
+ * ins Modell kommt, den Rueckfall senkt (dieselbe Lektion muss kein zweites Mal
+ * geschrieben werden). Diese Datei baut nur das Messgeraet. Sie startet nichts.
+ *
+ * Ohne den Schalter `CACHLY_VERSUCH=an` (siehe `versuchStart`) aendert sich am
+ * Verhalten des Recall-Pfads NICHTS — kein Zurueckhalten, kein Schreiben nach
+ * Redis, keine Markierung im Text. Das ist keine Nebenbedingung, das ist der
+ * ganze Zweck: der Versuch soll erst beginnen, wenn Heinrich ihn startet.
+ *
+ * ── Der Kanarienvogel ────────────────────────────────────────────────────────
+ *
+ * Zu pruefen ist nicht, ob eine Lektion ABGERUFEN wurde. Zu pruefen ist, ob ihr
+ * Text VOLLSTAENDIG in der Antwort landet, die das Modell sieht. Anlass: eine
+ * Lektion trug die gesuchte Adresse an Zeichen 323 von `what_worked`, die
+ * Anzeige schnitt bei 100 Zeichen ab (siehe lesson-preview.ts). Die Lektion war
+ * eingeblendet, der Fehler passierte trotzdem — genau der Zustand, den ein
+ * "wurde abgerufen"-Zaehler nie sieht.
+ *
+ * Die Markierung sitzt deshalb am Ende von `what_worked` — dem Feld, an dem der
+ * Anlass hing, und dem Feld, das `lessonPreviewLines` als Erstes und am
+ * grosszuegigsten kuerzt. Sie besteht aus acht Zero-Width-Space-Zeichen
+ * (U+200B): unsichtbar in jedem Renderer (Terminal, Markdown, HTML), und sie
+ * uebersteht sowohl `flat()`s Leerzeichen-Kollaps als auch `String#trim()` —
+ * beide fassen nur "richtige" Leerzeichen an, U+200B gehoert zu keiner der
+ * beiden Kategorien. Acht Wiederholungen, damit ein einzelnes zufaelliges
+ * Zero-Width-Zeichen in echtem Nutzertext die Markierung nicht vortaeuscht.
+ *
+ * WICHTIG: die Markierung wird NICHT roh ans Ende des JSON-Strings gehaengt.
+ * Das wuerde `JSON.parse` in `recallVorschau` brechen und den Fallback-Pfad
+ * (rohes `trimTo` ueber das GANZE JSON-Objekt) erzwingen — einen Pfad, den
+ * echte, unmarkierte Lektionen nie durchlaufen. Das Ergebnis waere ein
+ * Fehlalarm, kein Messwert. Die Markierung wird darum in die geparste
+ * `what_worked`-Zeichenkette eingefuegt, das Objekt bleibt gueltiges JSON, und
+ * der Kanarienvogel durchlaeuft exakt den Pfad, den eine echte Lektion auch
+ * durchlaeuft.
+ *
+ * Geprueft wird am Ende die WIRKLICH zusammengebaute Antwort (`lines.join`),
+ * nicht eine Nebenrechnung — siehe `schliesseVersuchAb`. Die Markierung wird
+ * danach aus dem Text entfernt, bevor er den Nutzer erreicht.
+ */
+import { randomBytes, createHash } from 'node:crypto';
+import { meldeEinmal } from './aussetzer.js';
+// ── Der Schalter ─────────────────────────────────────────────────────────────
+export const VERSUCH_ENV = 'CACHLY_VERSUCH';
+export const VERSUCH_SALZ_ENV = 'CACHLY_VERSUCH_SALZ';
+/** Grund fuer `meldeEinmal`: Versuch eingeschaltet, aber kein Salz gesetzt. */
+export const OHNE_SALZ = 'versuch-ohne-salz';
+/**
+ * Der einzige Einstiegspunkt fuer die Frage "soll der Versuch jetzt laufen?".
+ *
+ * Gibt das Salz zurueck, wenn ja — sonst `null`. Zwei Faelle enden bei `null`:
+ * der Schalter steht nicht auf "an", oder er steht auf "an", aber das Salz
+ * fehlt. Der zweite Fall meldet sich einmal je Prozess nach stderr (ueber
+ * `meldeEinmal`) und verhaelt sich danach wie der erste — still weiterlaufen
+ * waere die Fehlerklasse, gegen die `aussetzer.ts` gebaut wurde.
+ */
+export function versuchStart() {
+    if (process.env[VERSUCH_ENV] !== 'an')
+        return null;
+    const salz = process.env[VERSUCH_SALZ_ENV];
+    if (!salz) {
+        meldeEinmal(OHNE_SALZ, `${VERSUCH_ENV}=an, aber ${VERSUCH_SALZ_ENV} fehlt — der Versuch verhaelt sich wie "aus"`);
+        return null;
+    }
+    return salz;
+}
+// ── Turn-Kennung ─────────────────────────────────────────────────────────────
+/**
+ * Eine neue, stabile Kennung je Recall-Aufruf.
+ *
+ * Im Recall-Pfad gibt es keine vorhandene Anfrage- oder Turn-Kennung, die man
+ * verlaengern koennte — `requester` ist ein Autorenname, `cachly:session:current`
+ * haelt Zustand je INSTANZ, nicht je Aufruf. Darum: Zeitstempel (sortierbar,
+ * in einer Zeile lesbar) plus vier zufaellige Byte, damit zwei Aufrufe in
+ * derselben Millisekunde nicht kollidieren.
+ */
+export function neueKennung() {
+    const zeit = new Date().toISOString().replace(/[-:.]/g, '').slice(0, 15); // 20260820T171523
+    const zufall = randomBytes(4).toString('hex');
+    return `${zeit}-${zufall}`;
+}
+/**
+ * Reine Funktion, ohne Netz testbar: Kennung + Salz -> HOLD oder DELIVER.
+ *
+ * Berechnung exakt wie oeffentlich angekuendigt: Kennung und Salz aneinander-
+ * haengen, SHA-256, die ersten VIER Hex-Ziffern als Zahl lesen, modulo 100.
+ * Unter 50 heisst HOLD, sonst DELIVER.
+ */
+export function zuteilung(kennung, salz) {
+    const hash = createHash('sha256').update(`${kennung}${salz}`).digest('hex');
+    const ersteVier = hash.slice(0, 4);
+    const zahl = parseInt(ersteVier, 16) % 100;
+    return zahl < 50 ? 'HOLD' : 'DELIVER';
+}
+// ── Zulassung ────────────────────────────────────────────────────────────────
+/** Ohne einen Treffer ueber dieser Punktzahl gibt es nichts zu messen. */
+export const ZULASSUNGS_SCHWELLE = 0;
+/** Gibt es ueberhaupt einen Treffer, der ueber der Schwelle liegt? */
+export function istZulassungsfaehig(hoechstePunktzahl, schwelle = ZULASSUNGS_SCHWELLE) {
+    return hoechstePunktzahl > schwelle;
+}
+/** Der Grund, warum eine Anfrage NICHT zulassungsfaehig ist — oder `undefined`. */
+export function zulassungsGrund(hoechstePunktzahl, schwelle = ZULASSUNGS_SCHWELLE) {
+    if (istZulassungsfaehig(hoechstePunktzahl, schwelle))
+        return undefined;
+    return `hoechste Punktzahl ${hoechstePunktzahl.toFixed(3)} liegt nicht ueber der Schwelle ${schwelle}`;
+}
+// ── Kanarienvogel ────────────────────────────────────────────────────────────
+/**
+ * Acht Zero-Width-Spaces. Siehe Dateikopf fuer die Begruendung der Wahl.
+ *
+ * Ueber String.fromCharCode, nicht als roher Unicode-Buchstabe im
+ * Quelltext — ein unsichtbares Zeichen zwischen Anfuehrungszeichen ist beim
+ * Lesen und in `git diff` nicht von "kein Zeichen" zu unterscheiden.
+ */
+export const KANARIEN_MARKIERUNG = String.fromCharCode(0x200b).repeat(8);
+/**
+ * Setzt die Kanarien-Markierung ans Ende des `what_worked`-Feldes.
+ *
+ * `inhalt` ist der rohe Redis-Wert, wie ihn `recallVorschau` bekommt — meist
+ * das JSON einer Lektion, manchmal (Kontext-Eintraege, Index) einfacher Text.
+ * Ist es eine Lektion mit `what_worked`, wandert die Markierung dorthin und
+ * das Objekt bleibt gueltiges JSON (Begruendung siehe Dateikopf). Sonst wird
+ * roh ans Ende angehaengt — das ist fuer Nicht-Lektionen korrekt, weil
+ * `recallVorschau` sie ohnehin nur als Rohtext kuerzt.
+ */
+export function markiereDatensatz(inhalt, markierung = KANARIEN_MARKIERUNG) {
+    try {
+        const objekt = JSON.parse(inhalt);
+        if (typeof objekt.what_worked === 'string') {
+            objekt.what_worked = `${objekt.what_worked}${markierung}`;
+            return JSON.stringify(objekt);
+        }
+    }
+    catch {
+        // kein JSON — Markierung ans Ende des Rohtexts, siehe unten
+    }
+    return `${inhalt}${markierung}`;
+}
+/**
+ * Ueberlebt die Markierung in der fertig zusammengebauten Antwort?
+ *
+ * Ueberlebt sie: der ganze Datensatz kam durch. Fehlt sie: er wurde gekuerzt.
+ */
+export function kanarienUeberlebt(fertigeAntwort, markierung = KANARIEN_MARKIERUNG) {
+    return fertigeAntwort.includes(markierung);
+}
+/** Entfernt die Markierung, bevor der Text den Nutzer erreicht. */
+export function entferneMarkierung(text, markierung = KANARIEN_MARKIERUNG) {
+    return text.split(markierung).join('');
+}
+// ── Themenschluessel ─────────────────────────────────────────────────────────
+const LEKTION_PRAEFIX = 'cachly:lesson:best:';
+/** Redis-Schluessel einer Lektion -> ihr Themenname (ohne Praefix). */
+export function themaVon(key) {
+    return key.startsWith(LEKTION_PRAEFIX) ? key.slice(LEKTION_PRAEFIX.length) : key;
+}
+// ── Protokoll je Turn ────────────────────────────────────────────────────────
+/** Hash der Frage — die Frage selbst wird nie gespeichert (Zusage des Artikels). */
+export function hashFrage(frage) {
+    return createHash('sha256').update(frage).digest('hex');
+}
+const TURN_TTL_SEKUNDEN = 90 * 24 * 60 * 60; // 90 Tage — der Versuch dauert 14
+/** Redis-Schluessel fuer den Protokoll-Eintrag einer Kennung. */
+export function turnSchluessel(kennung) {
+    return `cachly:versuch:turn:${kennung}`;
+}
+/**
+ * Schreibt den Turn-Eintrag. Schlaegt das fehl, wird NICHTS geworfen — der
+ * Nutzer wartet auf eine Antwort, nicht auf ein Protokoll.
+ */
+export async function schreibeTurnProtokoll(redis, kennung, protokoll) {
+    try {
+        await redis.set(turnSchluessel(kennung), JSON.stringify(protokoll), 'EX', TURN_TTL_SEKUNDEN);
+    }
+    catch {
+        // Ein fehlendes Protokoll ist besser als eine gescheiterte Suche.
+    }
+}
+/**
+ * Wendet Zulassung + Zuteilung auf eine Trefferliste an. Reine Funktion,
+ * mutiert `treffer` nicht.
+ *
+ * Ohne zulassungsfaehigen Treffer passiert nichts — Zuteilung wird trotzdem
+ * berechnet und protokolliert, aber es gibt nichts zurueckzuhalten oder zu
+ * markieren. Bei HOLD verschwindet der beste Treffer aus der Liste, die
+ * uebrigen bleiben unveraendert. Bei DELIVER traegt der beste Treffer danach
+ * die Kanarien-Markierung.
+ */
+export function wendeZuteilungAn(treffer, kennung, salz, hoechstePunktzahl, schwelle = ZULASSUNGS_SCHWELLE) {
+    const zulassungsfaehig = istZulassungsfaehig(hoechstePunktzahl, schwelle);
+    const grund = zulassungsGrund(hoechstePunktzahl, schwelle);
+    const entscheidung = zuteilung(kennung, salz);
+    if (!zulassungsfaehig || treffer.length === 0) {
+        return {
+            treffer: [...treffer],
+            zuteilung: entscheidung,
+            zulassungsfaehig,
+            zulassungsGrund: grund,
+            markierungGesetzt: false,
+        };
+    }
+    const [bester, ...rest] = treffer;
+    if (entscheidung === 'HOLD') {
+        return {
+            treffer: rest,
+            zuteilung: entscheidung,
+            zulassungsfaehig,
+            zulassungsGrund: grund,
+            markierungGesetzt: false,
+            weggelassenesThema: themaVon(bester.key),
+        };
+    }
+    const markiert = { ...bester, content: markiereDatensatz(bester.content) };
+    return {
+        treffer: [markiert, ...rest],
+        zuteilung: entscheidung,
+        zulassungsfaehig,
+        zulassungsGrund: grund,
+        markierungGesetzt: true,
+    };
+}
+/**
+ * Letzter Schritt: prueft den Kanarienvogel gegen die WIRKLICH zusammen-
+ * gebaute Antwort, entfernt die Markierung, schreibt das Protokoll (fire-and-
+ * forget) und gibt den bereinigten Text zurueck — den, den der Nutzer sieht.
+ */
+export function schliesseVersuchAb(redis, kennung, teil, fertigeAntwort) {
+    const kanarienBestanden = teil.markierungGesetzt ? kanarienUeberlebt(fertigeAntwort) : false;
+    const bereinigt = entferneMarkierung(fertigeAntwort);
+    const protokoll = {
+        ts: new Date().toISOString(),
+        frageHash: hashFrage(teil.frage),
+        hoechstePunktzahl: teil.hoechstePunktzahl,
+        themen: teil.themen,
+        zulassungsfaehig: teil.zulassungsfaehig,
+        zulassungsGrund: teil.zulassungsGrund,
+        zuteilung: teil.zuteilung,
+        weggelassenesThema: teil.weggelassenesThema,
+        kanarienBestanden,
+    };
+    void schreibeTurnProtokoll(redis, kennung, protokoll);
+    return bereinigt;
+}
+//# sourceMappingURL=versuch.js.map

package/dist/src/versuch.js.map

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

package/dist/src/vorspann.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Der Vorspann einer Lektion — die ersten 100 Zeichen, und nur die.
+ *
+ * GEMESSEN am 16.08.2026: Das Session-Briefing zeigt je Lektion rund 100
+ * Zeichen. In `node4:einrichtung-contabo-und-fallen` stand die gesuchte
+ * Adresse `10.8.0.7` an Zeichen 323, und die passende Warnung im Feld
+ * `what_failed`, das im Briefing gar nicht erscheint. Die Lektion war
+ * eingeblendet. Der Fehler passierte trotzdem.
+ *
+ * Die Abhilfe war eine SCHREIBREGEL, kein Codefix: die entscheidende Tatsache
+ * gehoert in die ersten 100 Zeichen — die Zahl, die Adresse, der Befehl. Nicht
+ * der Anlass, nicht die Ausstattung, nicht die Vorgeschichte.
+ *
+ * Eine Regel, die kein Skript prueft, ist aber kein Gesetz, sondern ein
+ * Wunsch. Dieses Modul prueft sie — im Moment des Schreibens, wo der Autor
+ * (Mensch oder Agent) die Lektion noch in der Hand hat.
+ *
+ * Bewusst ein HINWEIS und keine Ablehnung: es gibt Lektionen ohne harte Zahl
+ * (eine Entscheidung, eine Richtung), und eine abgelehnte Lektion ist immer
+ * schlechter als eine unscharf formulierte.
+ */
+/** So viel sieht die naechste Sitzung im Briefing. Gemessen, nicht geschaetzt. */
+export declare const VORSPANN_ZEICHEN = 100;
+export interface VorspannBefund {
+    /** Die ersten VORSPANN_ZEICHEN Zeichen — das, was die naechste Sitzung sieht. */
+    vorspann: string;
+    /** Traegt der Vorspann mindestens eine harte Tatsache? */
+    traegtTatsache: boolean;
+    /** Welche Muster gegriffen haben (leer, wenn keines). */
+    gefunden: string[];
+    /**
+     * Steht die erste harte Tatsache erst HINTER dem Vorspann? Dann ist die
+     * Lektion nicht inhaltsleer — sie ist nur falsch herum geschrieben, und
+     * genau dieser Fall ist der teure.
+     */
+    tatsacheStehtSpaeter: boolean;
+    /** Position der ersten harten Tatsache im ganzen Text, oder -1. */
+    ersteTatsacheBei: number;
+    /**
+     * Endet der Vorspann MITTEN im Satz?
+     *
+     * GEMESSEN am 19.08.2026 an einer selbst geschriebenen Lektion. Ihre ersten
+     * 100 Zeichen lauteten:
+     *
+     *   "109 Testdateien lesen Quelltext, 102 OHNE Kommentar-Filter, 13 davon
+     *    GRUEN weil"
+     *
+     * Drei Zahlen, alle drei da — und genau bei "weil" ist Schluss. Das Briefing
+     * zeigt also die Zahlen, aber nicht, WOFUER sie stehen. Wer das liest, weiss
+     * nicht, ob 13 gut oder schlecht ist.
+     *
+     * Die Tatsachen-Pruefung allein war zufrieden, und zu Recht — die Zahlen
+     * stehen ja vorn. Was fehlte, war ihre Wirkung, und die passt fast immer in
+     * denselben Satz: "13 Waechter waren gruen, ohne etwas zu pruefen" sind 47
+     * Zeichen und vollstaendig.
+     */
+    abgeschnitten: boolean;
+}
+/**
+ * Prueft den Vorspann von `what_worked`.
+ *
+ * Leerer oder fehlender Text ergibt einen Befund ohne Tatsache und ohne
+ * "steht spaeter" — es gibt dann nichts umzustellen, sondern nichts zu lesen.
+ */
+export declare function pruefeVorspann(whatWorked: string | null | undefined): VorspannBefund;
+/**
+ * Ein Satz fuer den Autor — oder null, wenn alles in Ordnung ist.
+ *
+ * Der Hinweis nennt die POSITION, wenn die Tatsache nur zu weit hinten steht.
+ * Ohne Zahl waere er eine Ermahnung; mit Zahl ist er eine Anweisung, die man
+ * in zehn Sekunden befolgen kann.
+ */
+export declare function vorspannHinweis(whatWorked: string | null | undefined): string | null;

package/dist/src/vorspann.js

@@ -0,0 +1,146 @@
+/**
+ * Der Vorspann einer Lektion — die ersten 100 Zeichen, und nur die.
+ *
+ * GEMESSEN am 16.08.2026: Das Session-Briefing zeigt je Lektion rund 100
+ * Zeichen. In `node4:einrichtung-contabo-und-fallen` stand die gesuchte
+ * Adresse `10.8.0.7` an Zeichen 323, und die passende Warnung im Feld
+ * `what_failed`, das im Briefing gar nicht erscheint. Die Lektion war
+ * eingeblendet. Der Fehler passierte trotzdem.
+ *
+ * Die Abhilfe war eine SCHREIBREGEL, kein Codefix: die entscheidende Tatsache
+ * gehoert in die ersten 100 Zeichen — die Zahl, die Adresse, der Befehl. Nicht
+ * der Anlass, nicht die Ausstattung, nicht die Vorgeschichte.
+ *
+ * Eine Regel, die kein Skript prueft, ist aber kein Gesetz, sondern ein
+ * Wunsch. Dieses Modul prueft sie — im Moment des Schreibens, wo der Autor
+ * (Mensch oder Agent) die Lektion noch in der Hand hat.
+ *
+ * Bewusst ein HINWEIS und keine Ablehnung: es gibt Lektionen ohne harte Zahl
+ * (eine Entscheidung, eine Richtung), und eine abgelehnte Lektion ist immer
+ * schlechter als eine unscharf formulierte.
+ */
+/** So viel sieht die naechste Sitzung im Briefing. Gemessen, nicht geschaetzt. */
+export const VORSPANN_ZEICHEN = 100;
+/**
+ * Was als "harte Tatsache" zaehlt.
+ *
+ * Jedes Muster steht fuer etwas, das man beim naechsten Mal ABSCHREIBEN will
+ * und nicht neu herausfinden: eine Adresse, ein Port, eine Zahl mit Einheit,
+ * ein Pfad, ein Befehl, eine Version, ein Schluessel-Wert-Paar.
+ */
+const HARTE_MUSTER = [
+    { name: 'IP-Adresse', re: /\b\d{1,3}(?:\.\d{1,3}){3}\b/ },
+    { name: 'Port', re: /:\d{2,5}\b/ },
+    { name: 'Zahl', re: /\b\d+(?:[.,]\d+)?\s*(?:%|s|ms|m|h|d|MB|GB|TB|KB|k|x|×|EUR|€|\$)?\b/ },
+    { name: 'Pfad', re: /(?:^|\s)(?:\/[\w.-]+){2,}|[A-Za-z]:\\[\w\\.-]+/ },
+    { name: 'Befehl oder Datei', re: /`[^`]+`|\b[\w-]+\.(?:ts|tsx|go|js|mjs|py|sh|yml|yaml|json|sql|env)\b/ },
+    // Ein Name in Grossbuchstaben mit mindestens zwei Unterstrichen ist in der
+    // Praxis immer eine Umgebungsvariable oder ein Schalter — also etwas zum
+    // Abschreiben. Zwei Unterstriche, damit nicht jedes betonte Wort greift.
+    // Der Doppelpunkt ist bewusst NICHT dabei. Er war zuerst erlaubt, und die
+    // Gegenprobe fing sofort den Fehlalarm: "WICHTIG:" ist ein betontes Wort,
+    // keine Angabe. Bleibt das Gleichheitszeichen (PORT=3095) und der Name mit
+    // mindestens zwei Unterstrichen, der in der Praxis immer eine
+    // Umgebungsvariable ist.
+    { name: 'Schluessel', re: /\b[A-Z][A-Z0-9]*(?:_[A-Z0-9]+){2,}\b|\b[A-Z][A-Z0-9_]{3,}\s*=/ },
+    { name: 'Version', re: /\bv?\d+\.\d+(?:\.\d+)?\b/ },
+];
+/**
+ * Steht im Vorspann ein abgeschlossener Gedanke?
+ *
+ * Mechanisch, nicht inhaltlich: gesucht wird ein Satzende (Punkt, Semikolon,
+ * Ausrufe- oder Fragezeichen) innerhalb der ersten 100 Zeichen. Findet sich
+ * keines, endet der Vorspann mitten im Satz.
+ *
+ * Absichtlich KEINE Bedeutungspruefung. Ein Waechter, der raet, ob ein Satz
+ * "vollstaendig genug" ist, schlaegt bei jeder zweiten Lektion falschen Alarm
+ * — und ein Waechter, der zu oft Nein sagt, wird abgeschaltet. Ein fehlendes
+ * Satzzeichen ist dagegen eine Tatsache.
+ *
+ * Ein Text, der insgesamt kuerzer ist als der Vorspann, gilt NICHT als
+ * abgeschnitten: dort steht alles, was es gibt.
+ */
+function endetMittenImSatz(text) {
+    if (text.length <= VORSPANN_ZEICHEN)
+        return false;
+    const vorspann = text.slice(0, VORSPANN_ZEICHEN);
+    // Zwei Feinheiten, beide am echten Fall gelernt:
+    //
+    // 1. Ein Punkt in "10.8.0.7" oder "v1.2" beendet keinen Satz — deshalb muss
+    //    auf das Satzzeichen ein Leerzeichen oder das Textende folgen.
+    // 2. Der DOPPELPUNKT zaehlt NICHT. Er leitet ein, er schliesst nicht ab.
+    //    Genau daran scheiterte die erste Fassung: "GEMESSEN 19.08.2026: 109
+    //    Testdateien ... 13 davon GRUEN weil" galt als abgeschlossen, weil der
+    //    Doppelpunkt nach dem Datum mitzaehlte. Der Satz endet dort aber nicht,
+    //    er faengt an.
+    return !/[.;!?](?:\s|$)/.test(vorspann);
+}
+/** Frueheste Fundstelle irgendeines harten Musters, oder -1. */
+function ersteFundstelle(text) {
+    let best = -1;
+    for (const m of HARTE_MUSTER) {
+        const treffer = m.re.exec(text);
+        if (!treffer)
+            continue;
+        const i = treffer.index;
+        if (best === -1 || i < best)
+            best = i;
+    }
+    return best;
+}
+/**
+ * Prueft den Vorspann von `what_worked`.
+ *
+ * Leerer oder fehlender Text ergibt einen Befund ohne Tatsache und ohne
+ * "steht spaeter" — es gibt dann nichts umzustellen, sondern nichts zu lesen.
+ */
+export function pruefeVorspann(whatWorked) {
+    const text = typeof whatWorked === 'string' ? whatWorked : '';
+    const vorspann = text.slice(0, VORSPANN_ZEICHEN);
+    const gefunden = HARTE_MUSTER.filter(m => m.re.test(vorspann)).map(m => m.name);
+    const ersteTatsacheBei = ersteFundstelle(text);
+    return {
+        vorspann,
+        traegtTatsache: gefunden.length > 0,
+        gefunden,
+        tatsacheStehtSpaeter: gefunden.length === 0 && ersteTatsacheBei >= VORSPANN_ZEICHEN,
+        ersteTatsacheBei,
+        abgeschnitten: endetMittenImSatz(text),
+    };
+}
+/**
+ * Ein Satz fuer den Autor — oder null, wenn alles in Ordnung ist.
+ *
+ * Der Hinweis nennt die POSITION, wenn die Tatsache nur zu weit hinten steht.
+ * Ohne Zahl waere er eine Ermahnung; mit Zahl ist er eine Anweisung, die man
+ * in zehn Sekunden befolgen kann.
+ */
+export function vorspannHinweis(whatWorked) {
+    const b = pruefeVorspann(whatWorked);
+    if (!b.vorspann.trim())
+        return null;
+    /*
+     * Die Zahl ist da, aber der Satz ist es nicht.
+     *
+     * Dieser Fall kam am 19.08.2026 dazu und ist der feinere: die alte Pruefung
+     * war zufrieden, weil drei Zahlen in den ersten 100 Zeichen standen — und
+     * genau bei "weil" war Schluss. Zahlen ohne ihre Wirkung sind im Briefing
+     * kein Wissen, sondern ein Raetsel.
+     */
+    if (b.traegtTatsache && b.abgeschnitten) {
+        return (`📏 **Der Vorspann endet mitten im Satz** — die Zahl steht vorn, ihre Wirkung nicht. ` +
+            `Das Briefing der nächsten Sitzung bricht bei ${VORSPANN_ZEICHEN} Zeichen ab und zeigt dann ` +
+            `eine Zahl ohne Bedeutung. Ein abgeschlossener Satz in den ersten ${VORSPANN_ZEICHEN} Zeichen ` +
+            `genügt: nicht „13 davon grün weil", sondern „13 Wächter waren grün, ohne etwas zu prüfen."`);
+    }
+    if (b.traegtTatsache)
+        return null;
+    if (b.tatsacheStehtSpaeter) {
+        return (`📏 **Die entscheidende Tatsache steht bei Zeichen ${b.ersteTatsacheBei}** — das Briefing der nächsten ` +
+            `Sitzung endet bei ${VORSPANN_ZEICHEN}. Stell die Zahl, Adresse oder den Befehl an den Anfang von ` +
+            `\`what_worked\`; die Vorgeschichte gehört ans Ende oder in \`context\`.`);
+    }
+    return (`📏 **In den ersten ${VORSPANN_ZEICHEN} Zeichen steht keine Zahl, Adresse oder Befehl** — nur so viel sieht ` +
+        `die nächste Sitzung im Briefing. Trägt diese Lektion eine harte Tatsache, gehört sie nach vorn.`);
+}
+//# sourceMappingURL=vorspann.js.map

package/dist/src/vorspann.js.map

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