@cachly-dev/mcp-server 0.10.129 → 0.10.131

package/dist/src/seltenheitsbestand.js

@@ -1,92 +1 @@
-/**
- * Die Seltenheit der Wörter im Bestand — einmal gelesen, dann stehend.
- *
- * ── Warum es das gibt ───────────────────────────────────────────────────────
- *
- * `bewerteTopf` (src/rangfolge.ts) gewichtet die Seltenheits-Deckung mit 1,3 —
- * dem höchsten Gewicht von allen. Sie zu rechnen verlangt die Wortstatistik
- * über den GANZEN Bestand, nicht nur über die Kandidaten.
- *
- * Diese Statistik bei jeder Frage neu aufzubauen wäre genau der Fehler, den
- * der Wortabgleich heute macht: gemessen am 19.08.2026 baut er seinen Index
- * bei JEDER Frage neu, 1,6 ms je Lektion — bei 2000 Lektionen 3,2 Sekunden,
- * womit das 3-Sekunden-Budget der automatischen Einblendung reißt.
- *
- * Also dasselbe Muster wie `Vektorbestand`: einmal laden, eine Minute lang
- * gültig, danach nachladen. Ein voller Lesevorgang je Minute statt einer je
- * Frage.
- *
- * ── Was hier NICHT passiert ─────────────────────────────────────────────────
- *
- * Es wird keine zweite Zerlegung gebaut. `inhaltsWoerter` und `grobStamm`
- * kommen aus rangfolge.ts — dieselben Funktionen, die auch der Sortierer
- * benutzt. Zwei Zerlegungen desselben Textes wären zwei Wahrheiten, und die
- * Deckung würde gegen eine Statistik gerechnet, die anders zählt als sie.
- */
-import { Seltenheit } from './rangfolge.js';
-const LEKTION_PRAEFIX = 'cachly:lesson:best:';
-/** Der Text einer Lektion, so wie ihn auch der Messstand bildet. */
-export function lektionsText(l) {
-    const s = (v) => (typeof v === 'string' ? v : '');
-    return [s(l.topic), s(l.what_worked), s(l.what_failed)].filter(Boolean).join(' ');
-}
-export class Seltenheitsbestand {
-    frischeMs;
-    seltenheit = null;
-    texte = new Map();
-    geladen = 0;
-    constructor(frischeMs = 60_000) {
-        this.frischeMs = frischeMs;
-    }
-    get groesse() { return this.texte.size; }
-    /** Der Wortschatz einer Lektion, oder ein leerer Text, wenn sie fehlt. */
-    textVon(topic) { return this.texte.get(topic) ?? ''; }
-    /**
-     * Alle Themen des Bestands.
-     *
-     * Wird für die Vorauswahl gebraucht: sie muss über ALLE Lektionen laufen,
-     * nicht nur über die, die zufällig einen bestimmten Vektor haben. Genau
-     * daran ist der erste Verdrahtungsversuch am 20.08.2026 gescheitert — die
-     * Vorauswahl lief nur über die 399 Lektionen mit Fehlertext, und die
-     * restlichen 108 konnten nicht mehr gefunden werden (Trefferlage 90 % auf
-     * 70 % gefallen).
-     */
-    themen() { return this.texte.keys(); }
-    /** Die Statistik selbst. `null`, solange nie geladen wurde. */
-    get statistik() { return this.seltenheit; }
-    async aktualisiere(redis, jetzt = Date.now()) {
-        if (this.seltenheit && jetzt - this.geladen < this.frischeMs)
-            return;
-        const schluessel = [];
-        let cursor = '0';
-        do {
-            const [next, gefunden] = await redis.scan(cursor, 'MATCH', `${LEKTION_PRAEFIX}*`, 'COUNT', 500);
-            cursor = next;
-            schluessel.push(...gefunden);
-        } while (cursor !== '0');
-        if (schluessel.length === 0)
-            return; // Lieber die alte Statistik als gar keine.
-        const texte = new Map();
-        for (let i = 0; i < schluessel.length; i += 100) {
-            const block = schluessel.slice(i, i + 100);
-            const werte = await redis.mget(...block);
-            for (const [j, roh] of werte.entries()) {
-                if (!roh)
-                    continue;
-                try {
-                    const o = JSON.parse(roh);
-                    const topic = typeof o.topic === 'string' && o.topic
-                        ? o.topic
-                        : block[j].slice(LEKTION_PRAEFIX.length);
-                    if (topic)
-                        texte.set(topic, lektionsText(o));
-                }
-                catch { /* eine kaputte Zeile ist ein Thema fuer doctor, nicht fuer den Recall */ }
-            }
-        }
-        this.texte = texte;
-        this.seltenheit = new Seltenheit([...texte.values()]);
-        this.geladen = jetzt;
-    }
-}
-//# sourceMappingURL=seltenheitsbestand.js.map
+import{Seltenheit as p}from"./rangfolge.js";const f="cachly:lesson:best:";function w(n){const t=s=>typeof s=="string"?s:"";return[t(n.topic),t(n.what_worked),t(n.what_failed)].filter(Boolean).join(" ")}class d{frischeMs;seltenheit=null;texte=new Map;geladen=0;constructor(t=6e4){this.frischeMs=t}get groesse(){return this.texte.size}textVon(t){return this.texte.get(t)??""}themen(){return this.texte.keys()}get statistik(){return this.seltenheit}async aktualisiere(t,s=Date.now()){if(this.seltenheit&&s-this.geladen<this.frischeMs)return;const i=[];let c="0";do{const[e,o]=await t.scan(c,"MATCH",`${f}*`,"COUNT",500);c=e,i.push(...o)}while(c!=="0");if(i.length===0)return;const h=new Map;for(let e=0;e<i.length;e+=100){const o=i.slice(e,e+100),u=await t.mget(...o);for(const[g,l]of u.entries())if(l)try{const r=JSON.parse(l),a=typeof r.topic=="string"&&r.topic?r.topic:o[g].slice(f.length);a&&h.set(a,w(r))}catch{}}this.texte=h,this.seltenheit=new p([...h.values()]),this.geladen=s}}export{d as Seltenheitsbestand,w as lektionsText};

package/dist/src/speicherlage.js

@@ -1,84 +1 @@
-/**
- * Was tut der Speicher WIRKLICH — nicht, was für ihn vorgesehen war.
- *
- * ── Warum es das gibt ───────────────────────────────────────────────────────
- *
- * Am 20.08.2026 stand ein Bestand bei 23,6 MB von 25 MB Tarifgrenze und lief
- * dabei auf der Räumungsregel `allkeys-lru`. Diese Regel löscht bei Platzmangel
- * die am längsten ungenutzte Lektion — ohne Meldung, ohne Fehler, ohne Spur.
- * Genau die alten, selten gebrauchten Lektionen sind aber oft die wertvollen.
- *
- * Das Ärgerliche daran: der Code war seit April richtig. `evictionPolicy` gibt
- * für jeden Tarif `volatile-lru` zurück, und ein Test bewacht das seither. Die
- * laufende Instanz hatte trotzdem `allkeys-lru`, weil ein Container den
- * Startbefehl behält, mit dem er erzeugt wurde. Eine Regeländerung im Code
- * erreicht bestehende Instanzen NICHT.
- *
- * Ein Test beweist die Absicht. Diese Prüfung misst den Zustand. Das ist nicht
- * dieselbe Frage, und die zweite hat monatelang niemand gestellt.
- *
- * ── Warum "nicht gemessen" ein eigenes Urteil ist ──────────────────────────
- *
- * `CONFIG GET` ist auf manchen verwalteten Speichern gesperrt. Wer das als
- * "in Ordnung" verbucht, baut genau den Fehler wieder ein: Stille als grün.
- * Deshalb hat diese Prüfung drei Ausgänge, nicht zwei — gut, Hinweis, und
- * "konnte nicht nachsehen".
- */
-/** Anteil der Belegung, 0 bis 1. `null`, wenn es keine Grenze gibt oder nichts ablesbar ist. */
-export function anteil(l) {
-    if (l.benutzt === null || l.grenze === null || l.grenze <= 0)
-        return null;
-    return l.benutzt / l.grenze;
-}
-const mb = (b) => `${(b / 1024 / 1024).toFixed(1)} MB`;
-/**
- * Das Urteil über eine Speicherlage.
- *
- * Die Reihenfolge ist Absicht: die stille Löschung steht vor der Füllung. Eine
- * halbvolle Instanz, die still löscht, ist gefährlicher als eine volle, die
- * laut scheitert.
- */
-export function beurteileSpeicher(l) {
-    const aus = [];
-    if (l.richtlinie === null) {
-        aus.push({
-            art: 'ungemessen',
-            text: 'Raeumungsregel nicht ablesbar (CONFIG GET gesperrt) — unbekannt, ob dieser Speicher bei Platzmangel still loescht.',
-        });
-    }
-    else if (l.richtlinie.startsWith('allkeys')) {
-        aus.push({
-            art: 'fehler',
-            text: `Raeumungsregel ist \`${l.richtlinie}\`: bei Platzmangel wird die am laengsten ungenutzte Lektion GELOESCHT, ohne Meldung. Ein Gedaechtnis darf nicht raeumen wie ein Zwischenspeicher. Richtig waere \`volatile-lru\` (raeumt nur, was ohnehin ablaeuft) oder \`noeviction\` (scheitert laut).`,
-        });
-    }
-    else if (l.richtlinie === 'volatile-lru' || l.richtlinie === 'noeviction') {
-        aus.push({ art: 'gut', text: `Raeumungsregel \`${l.richtlinie}\` — Lektionen ohne Ablaufdatum sind sicher.` });
-    }
-    else {
-        aus.push({ art: 'hinweis', text: `Raeumungsregel \`${l.richtlinie}\` — ungeprueft fuer diesen Zweck.` });
-    }
-    const a = anteil(l);
-    if (l.benutzt === null) {
-        aus.push({ art: 'ungemessen', text: 'Belegung nicht ablesbar.' });
-    }
-    else if (a === null) {
-        aus.push({ art: 'hinweis', text: `${mb(l.benutzt)} belegt, keine Obergrenze gesetzt — dieser Speicher waechst, bis der Rechner voll ist.` });
-    }
-    else if (a >= 0.9) {
-        aus.push({ art: 'fehler', text: `${mb(l.benutzt)} von ${mb(l.grenze)} belegt (${Math.round(a * 100)} %). Die naechsten Lektionen scheitern bald.` });
-    }
-    else if (a >= 0.75) {
-        aus.push({ art: 'hinweis', text: `${mb(l.benutzt)} von ${mb(l.grenze)} belegt (${Math.round(a * 100)} %).` });
-    }
-    else {
-        aus.push({ art: 'gut', text: `${mb(l.benutzt)} von ${mb(l.grenze)} belegt (${Math.round(a * 100)} %).` });
-    }
-    return aus;
-}
-/** Eine Zahl aus einem INFO-Block, z. B. `used_memory`. `null`, wenn sie fehlt. */
-export function zahlAusInfo(info, name) {
-    const t = new RegExp(`^${name}:(\\d+)`, 'm').exec(info);
-    return t ? Number(t[1]) : null;
-}
-//# sourceMappingURL=speicherlage.js.map
+function r(e){return e.benutzt===null||e.grenze===null||e.grenze<=0?null:e.benutzt/e.grenze}const i=e=>`${(e/1024/1024).toFixed(1)} MB`;function u(e){const t=[];e.richtlinie===null?t.push({art:"ungemessen",text:"Raeumungsregel nicht ablesbar (CONFIG GET gesperrt) \u2014 unbekannt, ob dieser Speicher bei Platzmangel still loescht."}):e.richtlinie.startsWith("allkeys")?t.push({art:"fehler",text:`Raeumungsregel ist \`${e.richtlinie}\`: bei Platzmangel wird die am laengsten ungenutzte Lektion GELOESCHT, ohne Meldung. Ein Gedaechtnis darf nicht raeumen wie ein Zwischenspeicher. Richtig waere \`volatile-lru\` (raeumt nur, was ohnehin ablaeuft) oder \`noeviction\` (scheitert laut).`}):e.richtlinie==="volatile-lru"||e.richtlinie==="noeviction"?t.push({art:"gut",text:`Raeumungsregel \`${e.richtlinie}\` \u2014 Lektionen ohne Ablaufdatum sind sicher.`}):t.push({art:"hinweis",text:`Raeumungsregel \`${e.richtlinie}\` \u2014 ungeprueft fuer diesen Zweck.`});const n=r(e);return e.benutzt===null?t.push({art:"ungemessen",text:"Belegung nicht ablesbar."}):n===null?t.push({art:"hinweis",text:`${i(e.benutzt)} belegt, keine Obergrenze gesetzt \u2014 dieser Speicher waechst, bis der Rechner voll ist.`}):n>=.9?t.push({art:"fehler",text:`${i(e.benutzt)} von ${i(e.grenze)} belegt (${Math.round(n*100)} %). Die naechsten Lektionen scheitern bald.`}):n>=.75?t.push({art:"hinweis",text:`${i(e.benutzt)} von ${i(e.grenze)} belegt (${Math.round(n*100)} %).`}):t.push({art:"gut",text:`${i(e.benutzt)} von ${i(e.grenze)} belegt (${Math.round(n*100)} %).`}),t}function s(e,t){const n=new RegExp(`^${t}:(\\d+)`,"m").exec(e);return n?Number(n[1]):null}export{r as anteil,u as beurteileSpeicher,s as zahlAusInfo};

package/dist/src/spuren.js

@@ -1,150 +1 @@
-/**
- * Trampelpfade: das System lernt die Fragen, mit denen man es wirklich sucht.
- *
- * ── Der Gedanke ─────────────────────────────────────────────────────────────
- *
- * Ein Immunsystem hält Andockstellen vorrätig — und nach jeder überstandenen
- * Infektion bleiben Gedächtniszellen zurück, die genau diesen Erreger beim
- * nächsten Mal sofort greifen. Die Andockstellen sind gebaut (`eingaenge.ts`,
- * die Fehlertexte). Das hier sind die Gedächtniszellen.
- *
- * Wenn eine Frage eine Lektion findet, ist diese Frage ein bewiesener Weg zu
- * ihr. Sie wird als eigener Eingang gespeichert — beim nächsten Mal ist der
- * Weg breiter.
- *
- * ── Warum erst beim ZWEITEN Mal ─────────────────────────────────────────────
- *
- * Der Bauplan wollte den Eingang speichern, sobald eine Lektion „benutzt oder
- * bestätigt" wurde. Dieses Signal gibt es nicht: der Server sieht, was er
- * ausgeliefert hat, nicht was jemand damit gemacht hat. Es zu erfinden wäre
- * eine Zahl ohne Deckung.
- *
- * Also das, was ein Trampelpfad wirklich ist: **Wiederholung.** Ein einzelnes
- * Durchqueren macht keinen Weg. Führt dieselbe Frage ZWEIMAL zu derselben
- * Lektion, ist sie ein Pfad — und braucht dafür keine Bestätigung von außen,
- * sondern nur Geduld.
- *
- * ── Was das kann, und was ausdrücklich nicht ────────────────────────────────
- *
- * ES HILFT: einer Frage, die die Lektion heute auf Platz 3 findet, morgen auf
- * Platz 1. Genau das ist der gemessene Engpass — 37 richtige Antworten liegen
- * im Topf und werden nicht gezeigt (`.agent/cachly/tor0-tor1-ergebnis.md`).
- *
- * ES HILFT NICHT: einer Frage, die die Lektion gar nicht findet. Die wird nie
- * aufgezeichnet, weil sie nie ankam. Dieser blinde Fleck ist der Grund, warum
- * die Fehlertext-Eingänge daneben bestehen bleiben — sie wirken ohne Nutzung.
- */
-import { packe } from './bedeutung.js';
-import { EINGANG_PRAEFIX } from './eingaenge.js';
-/** Wo die noch unbewiesenen Spuren liegen: Frage → wie oft sie hierher führte. */
-export const SPUR_PRAEFIX = 'cachly:lesson:spur:';
-/**
- * Wo die bewiesenen Pfade liegen — als eigener Hash, NICHT im Eingangs-Hash.
- *
- * Grund: `schreibeEingaenge` löscht seinen Hash vor jedem Schreiben, damit die
- * Fehlertexte einer alten Fassung nicht neben denen der neuen stehen bleiben.
- * Lägen die gelernten Fragen dort, würde jedes erneute Lernen der Lektion die
- * gesammelte Erfahrung wegwerfen — ein Gedächtnis, das beim Dazulernen
- * vergisst.
- */
-export const PFAD_PRAEFIX = 'cachly:lesson:pfad:';
-/** Ab wie vielen Malen eine Frage als Pfad gilt. Einmal ist Zufall. */
-export const PFAD_SCHWELLE = 2;
-/** Höchstens so viele gelernte Fragen je Lektion. Der schwächste weicht. */
-export const PFAD_KAPPE = 8;
-/** Nur Fragen dieser Länge werden aufgezeichnet. */
-const MIN_LAENGE = 8;
-const MAX_LAENGE = 200;
-/**
- * Zwei Fragen, die sich nur in Zeichensetzung und Grossschreibung
- * unterscheiden, sind derselbe Weg.
- *
- * Bewusst KEIN Stammformen-Verfahren: am 19.08.2026 gemessen kostete
- * Stammbildung drei Punkte Findequote. Hier geht es ausserdem um Gleichheit,
- * nicht um Ähnlichkeit — wer „docker startet nicht" und „Docker startet
- * nicht!" trennt, zählt zweimal halb statt einmal ganz.
- */
-export function spurSchluessel(frage) {
-    return frage
-        .toLowerCase()
-        .replace(/[^\p{L}\p{N}\s]/gu, ' ')
-        .replace(/\s+/g, ' ')
-        .trim()
-        .slice(0, MAX_LAENGE);
-}
-/** Taugt diese Frage überhaupt als Pfad? */
-export function taugtAlsSpur(frage) {
-    const k = spurSchluessel(frage);
-    // Eine Frage aus einem einzigen Wort ist kein Weg, sondern ein Stichwort —
-    // sie würde jede Lektion an sich ziehen, die dieses Wort enthält.
-    return k.length >= MIN_LAENGE && k.split(' ').length >= 2;
-}
-/**
- * Welche Fragen sollen ihre Kappe überleben?
- *
- * Absteigend nach Häufigkeit; bei Gleichstand gewinnt die kürzere. Eine kurze
- * Frage, die genauso oft hierher führte, ist die allgemeinere — sie fängt mehr
- * Formulierungen als ihre lange Schwester.
- */
-export function behalte(pfade, kappe = PFAD_KAPPE) {
-    return pfade
-        .slice()
-        .sort((a, b) => b.anzahl - a.anzahl || a.frage.length - b.frage.length)
-        .slice(0, kappe);
-}
-/**
- * Zeichnet auf, dass diese Frage zu diesen Lektionen geführt hat, und macht
- * aus einer Spur einen Pfad, sobald sie sich wiederholt.
- *
- * Bewusst KEIN await beim Aufrufer nötig: wer sucht, soll nicht warten, bis
- * das Gedächtnis nachgeführt ist. Fällt es aus, ist die Suche trotzdem
- * beantwortet — der Pfad entsteht dann eben beim nächsten Mal.
- *
- * @returns wie viele Fragen zu Pfaden befördert wurden
- */
-export async function spurLegen(redis, frage, themen, einbetten) {
-    if (!taugtAlsSpur(frage) || themen.length === 0)
-        return 0;
-    const schluessel = spurSchluessel(frage);
-    let befoerdert = 0;
-    for (const topic of themen) {
-        const spurKey = `${SPUR_PRAEFIX}${topic}`;
-        const pfadKey = `${PFAD_PRAEFIX}${topic}`;
-        // Schon ein Pfad? Dann nur mitzaehlen, nicht noch einmal einbetten.
-        const istPfad = await redis.hexists(pfadKey, schluessel);
-        const anzahl = await redis.hincrby(spurKey, schluessel, 1);
-        if (istPfad || anzahl < PFAD_SCHWELLE)
-            continue;
-        // Eingebettet wird die FRAGE, wiedererkannt wird der Schluessel.
-        //
-        // Zwei verschiedene Aufgaben: der Schluessel muss "Docker startet nicht!"
-        // und "docker startet nicht" als denselben Weg erkennen — dafuer ist er
-        // kleingeschrieben und ohne Zeichensetzung. Fuer die Bedeutung ist genau
-        // das ein Verlust: im Deutschen traegt die Grossschreibung, ob "Sein" ein
-        // Hauptwort ist. Also wird der Originalwortlaut eingebettet.
-        const v = await einbetten(frage.trim().slice(0, MAX_LAENGE));
-        if (!v?.length)
-            continue;
-        await redis.hset(pfadKey, schluessel, packe(v));
-        befoerdert++;
-        // Kappe durchsetzen: der am seltensten begangene Pfad weicht.
-        const alle = await redis.hkeys(pfadKey);
-        if (alle.length > PFAD_KAPPE) {
-            const zaehler = await redis.hgetall(spurKey);
-            const mitAnzahl = alle.map((f) => ({ frage: f, anzahl: Number(zaehler[f] ?? 0) }));
-            const bleiben = new Set(behalte(mitAnzahl).map((x) => x.frage));
-            const raus = alle.filter((f) => !bleiben.has(f));
-            if (raus.length)
-                await redis.hdel(pfadKey, ...raus);
-        }
-    }
-    return befoerdert;
-}
-/**
- * Was `Eingangsbestand` laden muss: beide Hashes.
- *
- * Steht hier und nicht in eingaenge.ts, damit die Reihenfolge der Module
- * eindeutig bleibt — spuren kennt eingaenge, nicht umgekehrt.
- */
-export const EINGANGS_PRAEFIXE = [EINGANG_PRAEFIX, PFAD_PRAEFIX];
-//# sourceMappingURL=spuren.js.map
+import{packe as _}from"./bedeutung.js";import{EINGANG_PRAEFIX as y}from"./eingaenge.js";const F="cachly:lesson:spur:",f="cachly:lesson:pfad:",I=2,g=8,L=8,A=200;function E(t){return t.toLowerCase().replace(/[^\p{L}\p{N}\s]/gu," ").replace(/\s+/g," ").trim().slice(0,A)}function z(t){const e=E(t);return e.length>=L&&e.split(" ").length>=2}function G(t,e=g){return t.slice().sort((o,s)=>s.anzahl-o.anzahl||o.frage.length-s.frage.length).slice(0,e)}async function R(t,e,o,s){if(!z(e)||o.length===0)return 0;const c=E(e);let r=0;for(const i of o){const p=`${F}${i}`,a=`${f}${i}`,P=await t.hexists(a,c),x=await t.hincrby(p,c,1);if(P||x<I)continue;const h=await s(e.trim().slice(0,A));if(!h?.length)continue;await t.hset(a,c,_(h)),r++;const l=await t.hkeys(a);if(l.length>g){const m=await t.hgetall(p),w=l.map(n=>({frage:n,anzahl:Number(m[n]??0)})),N=new Set(G(w).map(n=>n.frage)),u=l.filter(n=>!N.has(n));u.length&&await t.hdel(a,...u)}}return r}const X=[y,f];export{X as EINGANGS_PRAEFIXE,g as PFAD_KAPPE,f as PFAD_PRAEFIX,I as PFAD_SCHWELLE,F as SPUR_PRAEFIX,G as behalte,R as spurLegen,E as spurSchluessel,z as taugtAlsSpur};

package/dist/src/starter-corpus.js

@@ -1,165 +1 @@
-/**
- * Curated starter corpus — universal, high-value engineering lessons.
- *
- * Loaded on demand via `brain_seed_starter` (or offered in the empty-brain
- * session_start welcome). The goal is to drop **time-to-first-recall** below
- * two minutes: a brand-new Brain (fresh repo, shallow clone, no fix-commits in
- * git history) would otherwise return nothing on the user's first query.
- *
- * Every lesson here is:
- *   - stack-agnostic or broadly applicable (no project-specific paths)
- *   - a real, common failure mode with a proven fix
- *   - free of secrets / PII
- *   - tagged `source: 'starter'` so it can be identified, filtered, or removed
- *
- * These ship inside the package — no network call needed to seed.
- */
-export const STARTER_CORPUS = [
-    {
-        topic: 'docker:layer-cache',
-        outcome: 'success',
-        what_worked: 'Copy package manifests (package.json/lock, go.mod, requirements.txt) and install deps BEFORE copying the rest of the source. Dependency layers then stay cached across code-only changes.',
-        what_failed: 'Build re-downloads all dependencies on every code change because `COPY . .` came before the install step, busting the cache.',
-        ctx: 'Slow Docker builds in CI — every commit reinstalls dependencies even when only app code changed.',
-        tags: ['docker', 'ci', 'build', 'cache', 'performance'],
-        confidence: 0.9,
-    },
-    {
-        topic: 'git:force-push-safety',
-        outcome: 'success',
-        what_worked: 'Use `git push --force-with-lease` instead of `--force`. It refuses to overwrite if the remote moved since your last fetch, protecting teammates\' commits.',
-        what_failed: 'A plain `git push --force` silently clobbered a colleague\'s commits that had landed after the last local fetch.',
-        ctx: 'Rebasing a shared feature branch and force-pushing the result.',
-        tags: ['git', 'rebase', 'collaboration', 'safety'],
-        confidence: 0.92,
-    },
-    {
-        topic: 'ci:flaky-tests-timing',
-        outcome: 'success',
-        what_worked: 'Pin time and randomness: use fake/frozen timers (e.g. vi.useFakeTimers, freezegun) and a fixed RNG seed. Replace arbitrary sleeps with explicit awaits on a condition.',
-        what_failed: 'Tests passed locally but failed ~10% of the time in CI due to real wall-clock timing and unseeded random data.',
-        ctx: 'Intermittent CI failures that disappear on re-run — classic flaky test.',
-        tags: ['ci', 'testing', 'flaky', 'timers', 'determinism'],
-        confidence: 0.85,
-    },
-    {
-        topic: 'node:esm-cjs-interop',
-        outcome: 'success',
-        what_worked: 'Set `"type": "module"` in package.json for ESM, use explicit `.js` extensions in relative imports, and `import { createRequire }` if you must load a CJS-only module.',
-        what_failed: '"ReferenceError: exports is not defined" / "Cannot use import statement outside a module" after mixing ESM and CommonJS.',
-        ctx: 'Migrating a Node project to ES modules or adding an ESM-only dependency.',
-        tags: ['node', 'esm', 'commonjs', 'modules', 'typescript'],
-        confidence: 0.85,
-    },
-    {
-        topic: 'jwt:clock-skew',
-        outcome: 'success',
-        what_worked: 'Allow a small leeway (30–60s) when validating `exp`/`nbf` claims, and keep server clocks synced with NTP. Most JWT libraries accept a `clockTolerance` option.',
-        what_failed: 'Valid tokens were rejected as expired because the auth server and API server clocks differed by a few seconds.',
-        ctx: 'Intermittent 401s right around token expiry across multiple services.',
-        tags: ['jwt', 'auth', 'clock', 'security', 'tokens'],
-        confidence: 0.88,
-    },
-    {
-        topic: 'postgres:migration-lock',
-        outcome: 'success',
-        what_worked: 'Set a short `lock_timeout` before DDL and add indexes with `CREATE INDEX CONCURRENTLY`. This avoids a migration blocking on a long-held table lock and stalling the whole deploy.',
-        what_failed: 'A migration hung indefinitely waiting for an ACCESS EXCLUSIVE lock while a long-running query held the table, blocking the deploy.',
-        ctx: 'Production deploy froze during a schema migration under live traffic.',
-        tags: ['postgres', 'database', 'migration', 'deploy', 'locking'],
-        confidence: 0.87,
-    },
-    {
-        topic: 'redis:eviction-policy',
-        outcome: 'success',
-        what_worked: 'Set `maxmemory` and an explicit `maxmemory-policy` (e.g. `allkeys-lru` for a cache, `noeviction` for a datastore). Always set TTLs on cache keys.',
-        what_failed: 'Redis silently evicted keys (or OOM-errored on writes) because no maxmemory policy was configured and keys never expired.',
-        ctx: 'Cache hit-rate cratered / writes started failing as Redis filled up.',
-        tags: ['redis', 'cache', 'memory', 'eviction', 'ttl'],
-        confidence: 0.86,
-    },
-    {
-        topic: 'k8s:oom-limits',
-        outcome: 'success',
-        what_worked: 'Set both memory `requests` and `limits` on every container. For JVM/Node, also cap the runtime heap below the container limit so the GC reclaims before the kernel OOM-kills.',
-        what_failed: 'Pods were OOMKilled (exit 137) and restarted in a loop because no memory limit was set and the node was overcommitted.',
-        ctx: 'Pod restarting repeatedly with OOMKilled status in kubectl describe.',
-        tags: ['kubernetes', 'oom', 'memory', 'limits', 'infra'],
-        confidence: 0.85,
-    },
-    {
-        topic: 'cors:preflight',
-        outcome: 'success',
-        what_worked: 'Handle the OPTIONS preflight explicitly and return the right Access-Control-Allow-{Origin,Methods,Headers}. For credentialed requests, echo a specific origin (never `*`) and set Allow-Credentials: true.',
-        what_failed: 'Browser blocked requests with "No \'Access-Control-Allow-Origin\' header" — the server never answered the preflight OPTIONS request.',
-        ctx: 'Frontend on a different origin gets CORS errors only in the browser (curl works fine).',
-        tags: ['cors', 'http', 'api', 'browser', 'preflight'],
-        confidence: 0.84,
-    },
-    {
-        topic: 'env:dotenv-precedence',
-        outcome: 'success',
-        what_worked: 'Know the precedence: real environment variables (and Docker `-e`/compose `environment`) override a `.env` file. Most loaders will NOT overwrite an already-set var. Audit with a startup log of effective config.',
-        what_failed: 'A value in `.env` was silently ignored in the container because an environment variable of the same name was already set by Docker.',
-        ctx: 'Config works locally but the container picks up the wrong value.',
-        tags: ['env', 'dotenv', 'docker', 'config'],
-        confidence: 0.83,
-    },
-    {
-        topic: 'async:unhandled-rejection',
-        outcome: 'success',
-        what_worked: 'Await or `.catch()` every promise. Add a process-level `unhandledRejection` handler that logs and exits non-zero, so a dropped rejection is loud, not silent.',
-        what_failed: 'A fire-and-forget promise rejected, the error vanished, and the process kept running in a broken state with no log.',
-        ctx: 'Mysterious missing data / silent failures with no stack trace in a Node service.',
-        tags: ['async', 'node', 'promises', 'error-handling'],
-        confidence: 0.84,
-    },
-    {
-        topic: 'sql:n-plus-one',
-        outcome: 'success',
-        what_worked: 'Eager-load related rows in one query (JOIN or the ORM\'s include/preload/select_related) instead of looping and querying per row. Verify with query logging or an APM trace.',
-        what_failed: 'An endpoint issued one query per item in a list (N+1), making latency scale linearly with result count.',
-        ctx: 'List endpoint gets slow as data grows; DB shows a flood of near-identical small queries.',
-        tags: ['sql', 'database', 'orm', 'performance', 'n+1'],
-        confidence: 0.86,
-    },
-    {
-        topic: 'http:retry-idempotency',
-        outcome: 'success',
-        what_worked: 'Only auto-retry idempotent requests (GET/PUT/DELETE) or POSTs guarded by an idempotency key. Use exponential backoff with jitter and a cap on attempts.',
-        what_failed: 'A retried POST created duplicate records because the first request actually succeeded but the response was lost.',
-        ctx: 'Duplicate charges / duplicate rows after adding naive retry logic to an HTTP client.',
-        tags: ['http', 'retry', 'idempotency', 'reliability', 'backoff'],
-        confidence: 0.85,
-    },
-    {
-        topic: 'cache:stampede',
-        outcome: 'success',
-        what_worked: 'Prevent thundering-herd recomputation on cache expiry with a short lock (single-flight) or early-recompute-with-jitter so only one request rebuilds the value while others serve the stale one.',
-        what_failed: 'When a hot cache key expired, hundreds of concurrent requests all missed and hammered the database simultaneously.',
-        ctx: 'Periodic DB load spikes that line up exactly with cache TTL expiry.',
-        tags: ['cache', 'stampede', 'performance', 'concurrency', 'redis'],
-        confidence: 0.83,
-    },
-    {
-        topic: 'security:no-secrets-in-logs',
-        outcome: 'success',
-        what_worked: 'Redact tokens, passwords, and full auth headers before logging. Log a token\'s prefix + length, never the value. Add a log scrubber/filter so it cannot regress.',
-        what_failed: 'A bearer token was written to application logs and ended up in the log aggregator, where it was searchable by anyone with log access.',
-        ctx: 'Security review found credentials in centralized logs.',
-        tags: ['security', 'logging', 'secrets', 'pii', 'compliance'],
-        confidence: 0.9,
-    },
-    {
-        topic: 'tls:cert-expiry',
-        outcome: 'success',
-        what_worked: 'Automate renewal (ACME/cert-manager) and alert at least 14 days before expiry. Monitor the leaf AND intermediate chain — clients fail if the chain is incomplete even when the leaf is valid.',
-        what_failed: 'A production outage hit when a TLS certificate silently expired over a weekend with no alerting in place.',
-        ctx: 'Sudden "certificate has expired" errors from clients; site unreachable over HTTPS.',
-        tags: ['tls', 'ssl', 'certificates', 'monitoring', 'infra'],
-        confidence: 0.88,
-    },
-];
-/** Stable count for changelog / docs. */
-export const STARTER_CORPUS_SIZE = STARTER_CORPUS.length;
-//# sourceMappingURL=starter-corpus.js.map
+const e=[{topic:"docker:layer-cache",outcome:"success",what_worked:"Copy package manifests (package.json/lock, go.mod, requirements.txt) and install deps BEFORE copying the rest of the source. Dependency layers then stay cached across code-only changes.",what_failed:"Build re-downloads all dependencies on every code change because `COPY . .` came before the install step, busting the cache.",ctx:"Slow Docker builds in CI \u2014 every commit reinstalls dependencies even when only app code changed.",tags:["docker","ci","build","cache","performance"],confidence:.9},{topic:"git:force-push-safety",outcome:"success",what_worked:"Use `git push --force-with-lease` instead of `--force`. It refuses to overwrite if the remote moved since your last fetch, protecting teammates' commits.",what_failed:"A plain `git push --force` silently clobbered a colleague's commits that had landed after the last local fetch.",ctx:"Rebasing a shared feature branch and force-pushing the result.",tags:["git","rebase","collaboration","safety"],confidence:.92},{topic:"ci:flaky-tests-timing",outcome:"success",what_worked:"Pin time and randomness: use fake/frozen timers (e.g. vi.useFakeTimers, freezegun) and a fixed RNG seed. Replace arbitrary sleeps with explicit awaits on a condition.",what_failed:"Tests passed locally but failed ~10% of the time in CI due to real wall-clock timing and unseeded random data.",ctx:"Intermittent CI failures that disappear on re-run \u2014 classic flaky test.",tags:["ci","testing","flaky","timers","determinism"],confidence:.85},{topic:"node:esm-cjs-interop",outcome:"success",what_worked:'Set `"type": "module"` in package.json for ESM, use explicit `.js` extensions in relative imports, and `import { createRequire }` if you must load a CJS-only module.',what_failed:'"ReferenceError: exports is not defined" / "Cannot use import statement outside a module" after mixing ESM and CommonJS.',ctx:"Migrating a Node project to ES modules or adding an ESM-only dependency.",tags:["node","esm","commonjs","modules","typescript"],confidence:.85},{topic:"jwt:clock-skew",outcome:"success",what_worked:"Allow a small leeway (30\u201360s) when validating `exp`/`nbf` claims, and keep server clocks synced with NTP. Most JWT libraries accept a `clockTolerance` option.",what_failed:"Valid tokens were rejected as expired because the auth server and API server clocks differed by a few seconds.",ctx:"Intermittent 401s right around token expiry across multiple services.",tags:["jwt","auth","clock","security","tokens"],confidence:.88},{topic:"postgres:migration-lock",outcome:"success",what_worked:"Set a short `lock_timeout` before DDL and add indexes with `CREATE INDEX CONCURRENTLY`. This avoids a migration blocking on a long-held table lock and stalling the whole deploy.",what_failed:"A migration hung indefinitely waiting for an ACCESS EXCLUSIVE lock while a long-running query held the table, blocking the deploy.",ctx:"Production deploy froze during a schema migration under live traffic.",tags:["postgres","database","migration","deploy","locking"],confidence:.87},{topic:"redis:eviction-policy",outcome:"success",what_worked:"Set `maxmemory` and an explicit `maxmemory-policy` (e.g. `allkeys-lru` for a cache, `noeviction` for a datastore). Always set TTLs on cache keys.",what_failed:"Redis silently evicted keys (or OOM-errored on writes) because no maxmemory policy was configured and keys never expired.",ctx:"Cache hit-rate cratered / writes started failing as Redis filled up.",tags:["redis","cache","memory","eviction","ttl"],confidence:.86},{topic:"k8s:oom-limits",outcome:"success",what_worked:"Set both memory `requests` and `limits` on every container. For JVM/Node, also cap the runtime heap below the container limit so the GC reclaims before the kernel OOM-kills.",what_failed:"Pods were OOMKilled (exit 137) and restarted in a loop because no memory limit was set and the node was overcommitted.",ctx:"Pod restarting repeatedly with OOMKilled status in kubectl describe.",tags:["kubernetes","oom","memory","limits","infra"],confidence:.85},{topic:"cors:preflight",outcome:"success",what_worked:"Handle the OPTIONS preflight explicitly and return the right Access-Control-Allow-{Origin,Methods,Headers}. For credentialed requests, echo a specific origin (never `*`) and set Allow-Credentials: true.",what_failed:`Browser blocked requests with "No 'Access-Control-Allow-Origin' header" \u2014 the server never answered the preflight OPTIONS request.`,ctx:"Frontend on a different origin gets CORS errors only in the browser (curl works fine).",tags:["cors","http","api","browser","preflight"],confidence:.84},{topic:"env:dotenv-precedence",outcome:"success",what_worked:"Know the precedence: real environment variables (and Docker `-e`/compose `environment`) override a `.env` file. Most loaders will NOT overwrite an already-set var. Audit with a startup log of effective config.",what_failed:"A value in `.env` was silently ignored in the container because an environment variable of the same name was already set by Docker.",ctx:"Config works locally but the container picks up the wrong value.",tags:["env","dotenv","docker","config"],confidence:.83},{topic:"async:unhandled-rejection",outcome:"success",what_worked:"Await or `.catch()` every promise. Add a process-level `unhandledRejection` handler that logs and exits non-zero, so a dropped rejection is loud, not silent.",what_failed:"A fire-and-forget promise rejected, the error vanished, and the process kept running in a broken state with no log.",ctx:"Mysterious missing data / silent failures with no stack trace in a Node service.",tags:["async","node","promises","error-handling"],confidence:.84},{topic:"sql:n-plus-one",outcome:"success",what_worked:"Eager-load related rows in one query (JOIN or the ORM's include/preload/select_related) instead of looping and querying per row. Verify with query logging or an APM trace.",what_failed:"An endpoint issued one query per item in a list (N+1), making latency scale linearly with result count.",ctx:"List endpoint gets slow as data grows; DB shows a flood of near-identical small queries.",tags:["sql","database","orm","performance","n+1"],confidence:.86},{topic:"http:retry-idempotency",outcome:"success",what_worked:"Only auto-retry idempotent requests (GET/PUT/DELETE) or POSTs guarded by an idempotency key. Use exponential backoff with jitter and a cap on attempts.",what_failed:"A retried POST created duplicate records because the first request actually succeeded but the response was lost.",ctx:"Duplicate charges / duplicate rows after adding naive retry logic to an HTTP client.",tags:["http","retry","idempotency","reliability","backoff"],confidence:.85},{topic:"cache:stampede",outcome:"success",what_worked:"Prevent thundering-herd recomputation on cache expiry with a short lock (single-flight) or early-recompute-with-jitter so only one request rebuilds the value while others serve the stale one.",what_failed:"When a hot cache key expired, hundreds of concurrent requests all missed and hammered the database simultaneously.",ctx:"Periodic DB load spikes that line up exactly with cache TTL expiry.",tags:["cache","stampede","performance","concurrency","redis"],confidence:.83},{topic:"security:no-secrets-in-logs",outcome:"success",what_worked:"Redact tokens, passwords, and full auth headers before logging. Log a token's prefix + length, never the value. Add a log scrubber/filter so it cannot regress.",what_failed:"A bearer token was written to application logs and ended up in the log aggregator, where it was searchable by anyone with log access.",ctx:"Security review found credentials in centralized logs.",tags:["security","logging","secrets","pii","compliance"],confidence:.9},{topic:"tls:cert-expiry",outcome:"success",what_worked:"Automate renewal (ACME/cert-manager) and alert at least 14 days before expiry. Monitor the leaf AND intermediate chain \u2014 clients fail if the chain is incomplete even when the leaf is valid.",what_failed:"A production outage hit when a TLS certificate silently expired over a weekend with no alerting in place.",ctx:'Sudden "certificate has expired" errors from clients; site unreachable over HTTPS.',tags:["tls","ssl","certificates","monitoring","infra"],confidence:.88}],t=e.length;export{e as STARTER_CORPUS,t as STARTER_CORPUS_SIZE};

package/dist/src/telemetry-types.js

@@ -1,13 +0,0 @@
-/**
- * Canonical types for the cachly telemetry event stream.
- *
- * These types form the contract between:
- *   - cachly-mcp  (emitter)  →  POST /api/v1/telemetry/mcp
- *   - cachly API  (receiver) →  resolves api_key → {org_id, user_id}, queues enriched event
- *   - cachly-insights ingest (consumer) ← reads enriched events from the resolved queue
- *
- * The ingest worker MUST NOT see raw JWTs or api_keys.  Resolution happens
- * exclusively inside the cachly API trust boundary before events reach the queue.
- */
-export {};
-//# sourceMappingURL=telemetry-types.js.map