@vascend/talos 0.1.0

package/dist/vascend/context-pareto.d.ts

@@ -0,0 +1,33 @@
+import type { EvaluatedPattern } from "./context-pattern-explorer.js";
+import type { ContextMetrics } from "./context-metrics.js";
+export type PatternMode = "fast" | "safe" | "deep" | "cheap" | "creative" | "surgical";
+export declare const PATTERN_MODES: readonly PatternMode[];
+export interface ParetoMetrics {
+    readonly quality: number;
+    readonly tokenEconomy: number;
+    readonly cleanliness: number;
+    readonly evidenceCoverage: number;
+    readonly decisionConsistency: number;
+    readonly novelty: number;
+}
+export interface ParetoPattern {
+    readonly id: string;
+    readonly family: string;
+    readonly label: string;
+    readonly metrics: ParetoMetrics;
+    readonly modeFit: Readonly<Record<PatternMode, number>>;
+    readonly dominated: boolean;
+    readonly dominatedBy: readonly string[];
+}
+export interface ParetoFront {
+    readonly patterns: readonly ParetoPattern[];
+    readonly frontier: readonly ParetoPattern[];
+    readonly bestByMode: Readonly<Record<PatternMode, string>>;
+}
+export declare function toParetoMetrics(m: ContextMetrics, score: number, tokenBudget?: number): ParetoMetrics;
+export declare function modeFit(metrics: ParetoMetrics, mode: PatternMode): number;
+export interface ParetoOptions {
+    readonly tokenBudget?: number;
+}
+export declare function buildParetoFront(evaluated: readonly EvaluatedPattern[], opts?: ParetoOptions): ParetoFront;
+export declare function formatParetoFront(front: ParetoFront): string;

package/dist/vascend/context-pareto.js

@@ -0,0 +1,165 @@
+// Pareto Pattern Explorer (metodo Danilov, Memory OS) -- L3: Optimization Layer.
+//
+// Il limite del Pattern Explorer e' che cerca UN solo qualityScore: un punteggio
+// scalare nasconde i trade-off. Un pattern puo' avere qualita' altissima ma
+// molti token; un altro qualita' buona ma latenza bassa; un altro coerenza
+// massima ma poca copertura.
+//
+// Questo modulo non sceglie un vincitore unico: estrae la FRONTIERA DI PARETO su
+// piu' metriche e, per ogni MODALITA' (fast/safe/deep/cheap/creative/surgical),
+// indica il pattern che la serve meglio.
+//
+//   pattern -> {quality, tokens, latency, staleRate, evidenceCoverage,
+//               decisionConsistency} -> frontiera -> modeFit per modalita'
+//
+// Modulo PURO e DETERMINISTICO: opera sui pattern gia' valutati dal Pattern
+// Explorer. Nessun side-effect, nessuna rete.
+export const PATTERN_MODES = [
+    "fast",
+    "safe",
+    "deep",
+    "cheap",
+    "creative",
+    "surgical",
+];
+// Estrae le metriche Pareto da un pattern valutato. tokenBudget normalizza
+// l'economia di token (default 4000, coerente col compiler). Deterministico.
+export function toParetoMetrics(m, score, tokenBudget = 4_000) {
+    const quality = clamp01(score / 100);
+    const tokenEconomy = clamp01(1 - m.counts.packTokens / Math.max(1, tokenBudget));
+    const cleanliness = clamp01(1 - m.staleMemoryRate);
+    return {
+        quality,
+        tokenEconomy,
+        cleanliness,
+        evidenceCoverage: clamp01(m.evidenceCoverage),
+        decisionConsistency: m.decisionConsistency ? 1 : 0,
+        novelty: clamp01(m.contextUtility / 20), // utile/1k come proxy, cap a 20
+    };
+}
+// Pesi di ogni modalita' sulle metriche Pareto. Sommano a ~1 per modalita'.
+const MODE_WEIGHTS = {
+    // fast: pochi token, latenza bassa (proxy: token economy alta) + qualita' decente.
+    fast: { tokenEconomy: 0.6, quality: 0.3, novelty: 0.1 },
+    // safe: coerenza decisioni + pulizia stale soprattutto.
+    safe: { decisionConsistency: 0.4, cleanliness: 0.4, quality: 0.2 },
+    // deep: copertura evidenza ampia + qualita'.
+    deep: { evidenceCoverage: 0.5, quality: 0.3, cleanliness: 0.2 },
+    // cheap: massima utilita' per token (economy + qualita').
+    cheap: { tokenEconomy: 0.5, quality: 0.4, cleanliness: 0.1 },
+    // creative: novelty alta, meno vincoli.
+    creative: { novelty: 0.5, quality: 0.3, evidenceCoverage: 0.2 },
+    // surgical: prove forti e poche (coverage + consistency + pulizia).
+    surgical: { evidenceCoverage: 0.35, decisionConsistency: 0.35, cleanliness: 0.3 },
+};
+// modeFit di un pattern per una modalita': somma pesata delle metriche Pareto.
+export function modeFit(metrics, mode) {
+    const weights = MODE_WEIGHTS[mode];
+    let sum = 0;
+    for (const key of Object.keys(weights)) {
+        sum += (weights[key] ?? 0) * metrics[key];
+    }
+    return round(sum);
+}
+// Vero se `a` domina `b`: a >= b su tutte le metriche e > su almeno una.
+function dominates(a, b) {
+    const keys = [
+        "quality",
+        "tokenEconomy",
+        "cleanliness",
+        "evidenceCoverage",
+        "decisionConsistency",
+        "novelty",
+    ];
+    let strictlyBetter = false;
+    for (const k of keys) {
+        if (a[k] < b[k] - 1e-9)
+            return false;
+        if (a[k] > b[k] + 1e-9)
+            strictlyBetter = true;
+    }
+    return strictlyBetter;
+}
+// Costruisce la frontiera di Pareto dai pattern valutati. Deterministico:
+// l'ordine dei pattern e i tie-break sono stabili sull'id.
+export function buildParetoFront(evaluated, opts = {}) {
+    const budget = opts.tokenBudget ?? 4_000;
+    const base = evaluated.map((e) => {
+        const metrics = toParetoMetrics(e.metrics, e.score, budget);
+        const fit = {
+            fast: modeFit(metrics, "fast"),
+            safe: modeFit(metrics, "safe"),
+            deep: modeFit(metrics, "deep"),
+            cheap: modeFit(metrics, "cheap"),
+            creative: modeFit(metrics, "creative"),
+            surgical: modeFit(metrics, "surgical"),
+        };
+        return {
+            id: e.id,
+            family: e.family,
+            label: e.label,
+            metrics,
+            modeFit: fit,
+            dominated: false,
+            dominatedBy: [],
+        };
+    });
+    // Marca i dominati.
+    const patterns = base.map((p) => {
+        const dominatedBy = [];
+        for (const q of base) {
+            if (q.id === p.id)
+                continue;
+            if (dominates(q.metrics, p.metrics))
+                dominatedBy.push(q.id);
+        }
+        dominatedBy.sort();
+        return { ...p, dominated: dominatedBy.length > 0, dominatedBy };
+    });
+    const frontier = patterns.filter((p) => !p.dominated).sort((a, b) => a.id.localeCompare(b.id));
+    // Miglior pattern per modalita' (tie-break su id).
+    const bestByMode = {};
+    for (const mode of PATTERN_MODES) {
+        let best = patterns[0];
+        for (const p of patterns) {
+            if (!best) {
+                best = p;
+                continue;
+            }
+            const d = p.modeFit[mode] - best.modeFit[mode];
+            if (d > 1e-9 || (Math.abs(d) <= 1e-9 && p.id.localeCompare(best.id) < 0))
+                best = p;
+        }
+        bestByMode[mode] = best ? best.id : "";
+    }
+    return { patterns, frontier, bestByMode };
+}
+// Diagnostica come blocco Danilov: frontiera + miglior pattern per modalita'.
+export function formatParetoFront(front) {
+    const lines = [
+        "[CONTEXT_PARETO]",
+        `@frontiera: ${front.frontier.length}/${front.patterns.length} pattern non-dominati`,
+        "--- frontiera ---",
+    ];
+    for (const p of front.frontier) {
+        lines.push(`@front[${p.id}] ${p.family}: q=${p.metrics.quality} tok=${p.metrics.tokenEconomy} clean=${p.metrics.cleanliness} cov=${p.metrics.evidenceCoverage}`);
+    }
+    lines.push("--- best per modalita' ---");
+    for (const mode of PATTERN_MODES) {
+        lines.push(`@mode[${mode}]: ${front.bestByMode[mode]}`);
+    }
+    lines.push("OUTPUT: scegli il pattern in base alla modalita' del task, non un solo best globale.");
+    return lines.join("\n");
+}
+function clamp01(v) {
+    if (Number.isNaN(v))
+        return 0;
+    if (v < 0)
+        return 0;
+    if (v > 1)
+        return 1;
+    return v;
+}
+function round(v) {
+    return Math.round(v * 1000) / 1000;
+}

package/dist/vascend/context-pattern-explorer.d.ts

@@ -0,0 +1,41 @@
+import { type TuneConfig, type QualityTargets } from "./context-autotuner.js";
+import type { ContextMetrics } from "./context-metrics.js";
+export type CompileWithConfigAsync = (config: TuneConfig) => ContextMetrics | Promise<ContextMetrics>;
+export type PatternFamily = "baseline" | "greedy" | "preset" | "perturbation" | "restart";
+export interface ConfigPattern {
+    readonly id: string;
+    readonly family: PatternFamily;
+    readonly label: string;
+    readonly config: TuneConfig;
+}
+export interface EvaluatedPattern extends ConfigPattern {
+    readonly metrics: ContextMetrics;
+    readonly score: number;
+    readonly delta: number;
+    readonly improves: boolean;
+}
+export interface PatternRanking {
+    readonly baselineScore: number;
+    readonly ranked: readonly EvaluatedPattern[];
+    readonly improvements: readonly EvaluatedPattern[];
+    readonly best: EvaluatedPattern;
+    readonly greedyScore: number;
+    readonly deepGain: number;
+    readonly evaluated: number;
+}
+export interface ExploreOptions {
+    readonly baseConfig?: TuneConfig;
+    readonly targets?: QualityTargets;
+    readonly perturbations?: number;
+    readonly seed?: number;
+    readonly multiStart?: boolean;
+    readonly greedyRounds?: number;
+}
+export declare function buildPatterns(compileSyncForGreedy: (config: TuneConfig) => ContextMetrics, opts?: ExploreOptions): ConfigPattern[];
+export declare function exploreContextPatterns(compile: CompileWithConfigAsync, opts?: ExploreOptions & {
+    readonly compileSyncForGreedy?: (config: TuneConfig) => ContextMetrics;
+}): Promise<PatternRanking>;
+export declare function formatPatternRanking(r: PatternRanking, opts?: {
+    readonly top?: number;
+}): string;
+export declare function patternRankingSummary(r: PatternRanking): string;

package/dist/vascend/context-pattern-explorer.js

@@ -0,0 +1,276 @@
+// Context Pattern Explorer (metodo Danilov, Memory OS) -- L4: l'auto-miglioramento DEEP.
+//
+// Il limite dell'autotuner (context-feedback-loop) e' che esplora UNA sola
+// traiettoria greedy: parte da una config, applica la diagnosi deterministica e
+// converge al primo OTTIMO LOCALE che incontra. Bastano metriche con piu' bacini
+// di attrazione perche' resti incastrato e NON veda config migliori altrove.
+//
+// Questo modulo va oltre il KPI: esplora in PROFONDITA' lo spazio di config
+// generando MOLTI pattern candidati in PARALLELO (preset architetturali +
+// perturbazioni deterministiche + l'esito greedy), valutandoli TUTTI con la
+// stessa compile, e CLASSIFICANDOLI in una lista ordinata di migliorie. La lista
+// non e' solo il vincitore: e' la mappa dei pattern che migliorano l'architettura
+// del context, ognuno con il suo delta misurato, cosi' le migliorie sono
+// ESPLICITE, in lista e classificate.
+//
+//   genera pattern[] --(parallelo)--> compile+score ognuno --> classifica per score
+//                                                              -> lista migliorie (delta vs baseline)
+//
+// Garanzie:
+//   - DETERMINISMO: stessa baseline + stessa compile => stessa lista (PRNG seedato).
+//   - DOMINANZA: il vincitore non e' mai PEGGIORE del greedy (greedy e' incluso
+//     come pattern, quindi la lista lo contiene e il top >= greedy).
+//   - PARALLELISMO: i pattern sono indipendenti (nessuno dipende dall'altro), la
+//     valutazione e' mappata in parallelo (Promise.all) senza ordine implicito.
+//
+// Modulo PURO rispetto alla compile iniettata: nessun side-effect proprio, niente
+// provider, niente rete. La compile incapsula l'unico mondo esterno (gli store).
+import { qualityScore, runFeedbackLoopGreedy, DEFAULT_CONFIG, DEFAULT_TARGETS, WEIGHT_BOUNDS, HIGH_BOUNDS, MID_BOUNDS, } from "./context-autotuner.js";
+// --- PRNG deterministico (mulberry32) ---------------------------------------
+// Generatore pseudo-casuale seedato: le perturbazioni devono essere RIPRODUCIBILI
+// (a parita' di seed, stessi pattern), altrimenti l'esploratore non e' deterministico.
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a |= 0;
+        a = (a + 0x6d2b79f5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+function clamp(v, lo, hi) {
+    if (!Number.isFinite(v))
+        return lo;
+    return Math.max(lo, Math.min(hi, v));
+}
+function round3(v) {
+    return Math.round(v * 1000) / 1000;
+}
+// Normalizza una config dentro i range sani (stessi bound dell'autotuner) e
+// mantiene l'invariante mid < high. Ogni pattern generato passa di qui.
+function sanitize(config) {
+    const w = config.weights;
+    const weights = {
+        relevance: clamp(round3(w.relevance), WEIGHT_BOUNDS.relevance[0], WEIGHT_BOUNDS.relevance[1]),
+        dependency: clamp(round3(w.dependency), WEIGHT_BOUNDS.dependency[0], WEIGHT_BOUNDS.dependency[1]),
+        trust: clamp(round3(w.trust), WEIGHT_BOUNDS.trust[0], WEIGHT_BOUNDS.trust[1]),
+        freshness: clamp(round3(w.freshness), WEIGHT_BOUNDS.freshness[0], WEIGHT_BOUNDS.freshness[1]),
+        novelty: clamp(round3(w.novelty), WEIGHT_BOUNDS.novelty[0], WEIGHT_BOUNDS.novelty[1]),
+        conflictRisk: clamp(round3(w.conflictRisk), WEIGHT_BOUNDS.conflictRisk[0], WEIGHT_BOUNDS.conflictRisk[1]),
+        tokenCost: clamp(round3(w.tokenCost), WEIGHT_BOUNDS.tokenCost[0], WEIGHT_BOUNDS.tokenCost[1]),
+    };
+    const high = clamp(round3(config.thresholds.high), HIGH_BOUNDS[0], HIGH_BOUNDS[1]);
+    const midRaw = clamp(round3(config.thresholds.mid), MID_BOUNDS[0], MID_BOUNDS[1]);
+    const mid = Math.min(midRaw, round3(high - 0.1));
+    return { weights, thresholds: { high, mid } };
+}
+// --- archetipi (preset) ------------------------------------------------------
+// Ogni preset incarna un'IPOTESI architetturale diversa sul context. Sono i
+// "bacini" che il greedy single-path da solo non visiterebbe mai. Partendo da
+// punti cosi' diversi, l'esplorazione copre regioni distinte dello spazio.
+function presetPatterns(base) {
+    const mk = (id, label, patch, th) => ({
+        id,
+        family: "preset",
+        label,
+        config: sanitize({
+            weights: { ...base.weights, ...patch },
+            thresholds: { ...base.thresholds, ...th },
+        }),
+    });
+    return [
+        // Corpo-pesante: piu' candidati entrano come evidenza (soglia HIGH bassa,
+        // rilevanza alta, costo token basso). Ipotesi: serve piu' corpo.
+        mk("preset-evidence-heavy", "corpo-pesante: piu' evidenza, soglia HIGH bassa", { relevance: 1.6, tokenCost: 0.1 }, { high: 0.8 }),
+        // Costo-pesante: prompt magro, paga caro ogni token (soglia HIGH alta).
+        // Ipotesi: il context e' gonfio, comprimere migliora la densita'.
+        mk("preset-cost-lean", "costo-pesante: prompt magro, soglia HIGH alta", { tokenCost: 0.6, relevance: 1.2 }, { high: 1.5 }),
+        // Conflict-pesante: caccia aggressiva agli obsoleti/contraddittori.
+        // Ipotesi: il rumore stale e' il problema dominante.
+        mk("preset-conflict-strict", "conflict-pesante: caccia gli obsoleti", { conflictRisk: 2.2, trust: 1.0 }, {}),
+        // Dipendenza-pesante: privilegia i nodi collegati (decisioni, prerequisiti).
+        // Ipotesi: la coerenza del grafo conta piu' della freschezza.
+        mk("preset-dependency-first", "dipendenza-pesante: privilegia il grafo", { dependency: 1.4, trust: 1.0, freshness: 0.3 }, {}),
+        // Freschezza-pesante: il recente domina (freshness e novelty alte).
+        // Ipotesi: il lavoro e' molto dinamico, il vecchio e' rumore.
+        mk("preset-recency-first", "freschezza-pesante: il recente domina", { freshness: 0.9, novelty: 0.8 }, {}),
+        // Bilanciato-largo: tutti i fattori a peso medio-alto, soglie centrali.
+        // Ipotesi: nessun fattore deve dominare.
+        mk("preset-balanced-wide", "bilanciato-largo: nessun fattore domina", { relevance: 1.3, dependency: 1.0, trust: 0.8, freshness: 0.6, novelty: 0.6, conflictRisk: 1.3, tokenCost: 0.25 }, { high: 1.0, mid: 0.45 }),
+    ];
+}
+// --- perturbazioni (search casuale deterministica) --------------------------
+// Genera N perturbazioni attorno a una config: jitter gaussiano-ish su ogni leva.
+// Esplora il vicinato della baseline in piu' direzioni CONTEMPORANEAMENTE (non
+// la sola direzione del gradiente greedy), cosi' scopre migliorie laterali.
+function perturbationPatterns(base, count, seed) {
+    const rnd = mulberry32(seed);
+    const out = [];
+    const jitter = (v, span) => v + (rnd() - 0.5) * 2 * span;
+    for (let i = 0; i < count; i++) {
+        const w = base.weights;
+        const config = sanitize({
+            weights: {
+                relevance: jitter(w.relevance, 0.4),
+                dependency: jitter(w.dependency, 0.35),
+                trust: jitter(w.trust, 0.3),
+                freshness: jitter(w.freshness, 0.3),
+                novelty: jitter(w.novelty, 0.3),
+                conflictRisk: jitter(w.conflictRisk, 0.5),
+                tokenCost: jitter(w.tokenCost, 0.2),
+            },
+            thresholds: {
+                high: jitter(base.thresholds.high, 0.25),
+                mid: jitter(base.thresholds.mid, 0.15),
+            },
+        });
+        out.push({ id: `perturb-${i + 1}`, family: "perturbation", label: `perturbazione #${i + 1} attorno alla baseline`, config });
+    }
+    return out;
+}
+// Costruisce l'INSIEME dei pattern candidati (senza valutarli): baseline +
+// greedy + preset + perturbazioni + restart. Esposta per i test (verifica che
+// le famiglie ci siano tutte e siano deterministiche).
+export function buildPatterns(compileSyncForGreedy, opts = {}) {
+    const base = sanitize(opts.baseConfig ?? DEFAULT_CONFIG);
+    const targets = opts.targets ?? DEFAULT_TARGETS;
+    const perturbations = opts.perturbations ?? 8;
+    const seed = opts.seed ?? 0x5eed;
+    const greedyRounds = opts.greedyRounds ?? 6;
+    const patterns = [];
+    // 1) Baseline: il riferimento (delta 0 per definizione).
+    patterns.push({ id: "baseline", family: "baseline", label: "config di partenza (riferimento)", config: base });
+    // 2) Greedy: l'esito dell'autotuner single-path = stato dell'arte attuale.
+    const greedy = runFeedbackLoopGreedy(compileSyncForGreedy, { config: base, targets, maxRounds: greedyRounds });
+    patterns.push({ id: "greedy", family: "greedy", label: "esito autotuner greedy (single-path)", config: sanitize(greedy.bestConfig) });
+    // 3) Preset: archetipi architetturali (bacini lontani dalla baseline).
+    const presets = presetPatterns(base);
+    patterns.push(...presets);
+    // 4) Perturbazioni: vicinato casuale deterministico della baseline.
+    patterns.push(...perturbationPatterns(base, perturbations, seed));
+    // 5) Restart (multi-start): greedy ripartito da OGNI preset. Scava i bacini
+    //    dei preset col gradiente, spesso trovando ottimi locali migliori.
+    if (opts.multiStart !== false) {
+        for (const p of presets) {
+            const r = runFeedbackLoopGreedy(compileSyncForGreedy, { config: p.config, targets, maxRounds: greedyRounds });
+            patterns.push({
+                id: `restart-${p.id}`,
+                family: "restart",
+                label: `greedy ripartito da ${p.label}`,
+                config: sanitize(r.bestConfig),
+            });
+        }
+    }
+    // Dedup per config identica (preset/perturbazioni possono collassare sullo
+    // stesso punto dopo il sanitize): tieni la prima (famiglia piu' informativa).
+    return dedupeByConfig(patterns);
+}
+// Dedup stabile per chiave-config: due pattern con identici pesi+soglie sono lo
+// stesso punto dello spazio; ne basta uno (il primo, gia' nell'ordine di priorita').
+// ECCEZIONE: baseline e greedy NON si deduplicano mai, anche se coincidono col
+// punto di partenza: sono riferimenti semantici (il greedy che non si muove e'
+// un'INFORMAZIONE, dice che il single-path e' gia' fermo li').
+function dedupeByConfig(list) {
+    const seen = new Set();
+    const out = [];
+    for (const p of list) {
+        const keep = p.family === "baseline" || p.family === "greedy";
+        const key = configKey(p.config);
+        if (!keep && seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(p);
+    }
+    return out;
+}
+function configKey(c) {
+    const w = c.weights;
+    return [w.relevance, w.dependency, w.trust, w.freshness, w.novelty, w.conflictRisk, w.tokenCost, c.thresholds.high, c.thresholds.mid]
+        .map((n) => n.toFixed(3))
+        .join("|");
+}
+// --- valutazione PARALLELA + classifica -------------------------------------
+// Esegue l'esplorazione DEEP: genera i pattern, li valuta TUTTI in parallelo con
+// la compile iniettata, e li CLASSIFICA in una lista ordinata di migliorie.
+//
+// Il greedy interno serve una compile sincrona; per il caso reale (compile
+// asincrona/costosa) passa anche `compileSyncForGreedy`, una versione sincrona
+// usata SOLO per derivare i punti di partenza greedy/restart. Se ometti quella
+// sincrona e la compile e' sincrona, viene riusata per entrambi.
+export async function exploreContextPatterns(compile, opts = {}) {
+    const targets = opts.targets ?? DEFAULT_TARGETS;
+    // Per generare i punti greedy serve una compile sincrona. Se non fornita,
+    // proviamo a usare `compile` assumendola sincrona (caso test/puro).
+    const syncCompile = opts.compileSyncForGreedy ?? ((config) => {
+        const r = compile(config);
+        if (r instanceof Promise) {
+            throw new Error("exploreContextPatterns: compile asincrona richiede compileSyncForGreedy per i punti greedy/restart");
+        }
+        return r;
+    });
+    const patterns = buildPatterns(syncCompile, opts);
+    // VALUTAZIONE IN PARALLELO: ogni pattern e' indipendente: nessuno usa il
+    // risultato di un altro. Promise.all li mappa tutti insieme.
+    const evaluated = await Promise.all(patterns.map(async (p) => {
+        const metrics = await compile(p.config);
+        const score = qualityScore(metrics, targets);
+        return { ...p, metrics, score, delta: 0, improves: false };
+    }));
+    // Baseline score = quello del pattern "baseline".
+    const baselinePat = evaluated.find((e) => e.id === "baseline");
+    const baselineScore = baselinePat ? baselinePat.score : Math.max(0, ...evaluated.map((e) => e.score));
+    // Calcola delta e flag miglioria rispetto alla baseline.
+    const withDelta = evaluated.map((e) => {
+        const delta = e.score - baselineScore;
+        return { ...e, delta, improves: delta > 0 };
+    });
+    // CLASSIFICA: score decrescente, poi delta, poi id stabile (determinismo).
+    const ranked = [...withDelta].sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        if (b.delta !== a.delta)
+            return b.delta - a.delta;
+        return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+    });
+    const improvements = ranked.filter((e) => e.improves);
+    const greedyPat = ranked.find((e) => e.family === "greedy");
+    const greedyScore = greedyPat ? greedyPat.score : baselineScore;
+    const best = ranked[0];
+    const deepGain = best.score - greedyScore;
+    return {
+        baselineScore,
+        ranked,
+        improvements,
+        best,
+        greedyScore,
+        deepGain,
+        evaluated: ranked.length,
+    };
+}
+// --- diagnostica / output Danilov -------------------------------------------
+// Formatta la classifica come blocco Danilov: la LISTA delle migliorie scoperte,
+// classificate, con famiglia/delta. E' la consegna richiesta dal goal: migliorie
+// in lista e classificate, oltre il solo KPI vincente.
+export function formatPatternRanking(r, opts) {
+    const top = opts?.top ?? r.ranked.length;
+    const lines = [
+        "[CONTEXT_PATTERN_EXPLORER]",
+        `@esplorazione: pattern_valutati=${r.evaluated} (in parallelo)`,
+        `@baseline: score=${r.baselineScore}`,
+        `@greedy: score=${r.greedyScore} (single-path, stato dell'arte)`,
+        `@deep: best=${r.best.score} via ${r.best.family}:${r.best.id}  deep_gain_su_greedy=${r.deepGain >= 0 ? "+" : ""}${r.deepGain}`,
+        `@migliorie: ${r.improvements.length} pattern migliorano la baseline`,
+        "--- classifica (score desc) ---",
+    ];
+    r.ranked.slice(0, top).forEach((e, i) => {
+        const tag = e.delta > 0 ? `+${e.delta}` : `${e.delta}`;
+        lines.push(`@rank[${i + 1}] ${e.family}:${e.id}  score=${e.score} (delta ${tag})  [ ${e.label} ]`);
+    });
+    lines.push("OUTPUT: adotta best.config come pesi/soglie; la lista classifica le migliorie alternative.");
+    return lines.join("\n");
+}
+// Vista compatta in una riga (per log/TUI).
+export function patternRankingSummary(r) {
+    return `deep-explore: ${r.evaluated} pattern, ${r.improvements.length} migliorie, best ${r.best.family}:${r.best.id} score=${r.best.score} (deep_gain ${r.deepGain >= 0 ? "+" : ""}${r.deepGain} su greedy)`;
+}

package/dist/vascend/context-regret.d.ts

@@ -0,0 +1,32 @@
+import type { ContextScore } from "./context-candidate.js";
+import type { ContextMetrics } from "./context-metrics.js";
+import type { LintReport } from "./context-lint.js";
+export interface RegretComponents {
+    readonly missedRelevantEvidence: number;
+    readonly staleLeaks: number;
+    readonly duplicateTokens: number;
+    readonly wrongLayoutPenalty: number;
+    readonly unnecessaryRecallCost: number;
+}
+export interface ContextRegret {
+    readonly regret: number;
+    readonly components: RegretComponents;
+}
+export interface RegretWeights {
+    readonly missedRelevantEvidence: number;
+    readonly staleLeaks: number;
+    readonly duplicateTokens: number;
+    readonly wrongLayoutPenalty: number;
+    readonly unnecessaryRecallCost: number;
+}
+export declare const DEFAULT_REGRET_WEIGHTS: RegretWeights;
+export interface RegretInput {
+    readonly scored: readonly ContextScore[];
+    readonly report: LintReport;
+    readonly metrics: ContextMetrics;
+    readonly includedIds?: ReadonlySet<string>;
+    readonly recallPlannedButUnused?: boolean;
+    readonly weights?: RegretWeights;
+}
+export declare function computeContextRegret(input: RegretInput): ContextRegret;
+export declare function formatContextRegret(r: ContextRegret): string;

package/dist/vascend/context-regret.js

@@ -0,0 +1,93 @@
+// Context Regret (metodo Danilov, Memory OS) -- nuova metrica centrale.
+//
+// qualityScore misura quanto e' buono un prompt. context_regret misura quanto
+// hai PERSO scegliendo questo prompt invece del migliore possibile osservato:
+//
+//   regret = bestKnownUtility - actualUtility
+//
+// Versione pratica, scomposta in componenti misurabili sul contesto compilato:
+//
+//   context_regret =
+//       missed_relevant_evidence  (prove rilevanti rimaste fuori)
+//     + stale_leaks               (obsoleti entrati)
+//     + duplicate_tokens          (ridondanza)
+//     + wrong_layout_penalty      (layout inefficace)
+//     + unnecessary_recall_cost   (recall non necessario)
+//
+// E' piu' forte del solo qualityScore perche' misura il COSTO dell'architettura
+// scelta, e alimenta l'aggiornamento di baseline / Pareto / pattern.
+//
+// Modulo PURO e DETERMINISTICO: opera su ContextScore + report di lint, nessun
+// side-effect, nessuna rete.
+export const DEFAULT_REGRET_WEIGHTS = {
+    missedRelevantEvidence: 1.0,
+    staleLeaks: 1.0,
+    duplicateTokens: 0.5,
+    wrongLayoutPenalty: 0.4,
+    unnecessaryRecallCost: 0.3,
+};
+// Stima il regret del contesto compilato. Deterministico.
+export function computeContextRegret(input) {
+    const weights = input.weights ?? DEFAULT_REGRET_WEIGHTS;
+    const scored = input.scored;
+    // missed_relevant_evidence: dei candidati HIGH (corpo-degni), quanto VALORE e'
+    // rimasto LOW/escluso. Approssimazione: quota di score positivo non incluso.
+    const highValue = scored.filter((s) => s.tier === "high");
+    const included = input.includedIds
+        ? scored.filter((score) => input.includedIds?.has(score.candidate.id))
+        : scored.filter((s) => s.tier !== "low");
+    const totalPositive = scored.reduce((acc, s) => acc + Math.max(0, s.score), 0) || 1;
+    const includedPositive = included.reduce((acc, s) => acc + Math.max(0, s.score), 0);
+    const missedRelevantEvidence = clamp01(1 - includedPositive / totalPositive);
+    // stale_leaks: la quota stale gia' calcolata dalle metriche.
+    const staleLeaks = clamp01(input.metrics.staleMemoryRate);
+    // duplicate_tokens: la novelty media bassa tra gli inclusi indica ridondanza.
+    const avgNovelty = included.length > 0
+        ? included.reduce((acc, s) => acc + s.factors.novelty, 0) / included.length
+        : 1;
+    const duplicateTokens = clamp01(1 - avgNovelty);
+    // wrong_layout_penalty: i findings del lint normalizzati (piu' problemi = peggio).
+    const findings = input.report.findings?.length ?? 0;
+    const wrongLayoutPenalty = clamp01(findings / 5);
+    // unnecessary_recall_cost: 1 se si e' pianificato recall poi non servito.
+    const unnecessaryRecallCost = input.recallPlannedButUnused ? 1 : 0;
+    const components = {
+        missedRelevantEvidence,
+        staleLeaks,
+        duplicateTokens,
+        wrongLayoutPenalty,
+        unnecessaryRecallCost,
+    };
+    const regret = round(weights.missedRelevantEvidence * components.missedRelevantEvidence +
+        weights.staleLeaks * components.staleLeaks +
+        weights.duplicateTokens * components.duplicateTokens +
+        weights.wrongLayoutPenalty * components.wrongLayoutPenalty +
+        weights.unnecessaryRecallCost * components.unnecessaryRecallCost);
+    return { regret, components };
+}
+// Diagnostica come blocco Danilov.
+export function formatContextRegret(r) {
+    const c = r.components;
+    return [
+        "[CONTEXT_REGRET]",
+        `@regret[totale]: ${r.regret}`,
+        `@comp[missed_evidence]: ${round(c.missedRelevantEvidence)}`,
+        `@comp[stale_leaks]: ${round(c.staleLeaks)}`,
+        `@comp[duplicate_tokens]: ${round(c.duplicateTokens)}`,
+        `@comp[wrong_layout]: ${round(c.wrongLayoutPenalty)}`,
+        `@comp[unnecessary_recall]: ${round(c.unnecessaryRecallCost)}`,
+        "OUTPUT: regret basso = il prompt si avvicina al migliore osservato; usa il delta per aggiornare baseline/Pareto.",
+    ].join("\n");
+}
+function clamp01(v) {
+    if (Number.isNaN(v))
+        return 0;
+    if (v < 0)
+        return 0;
+    if (v > 1)
+        return 1;
+    return v;
+}
+function round(v) {
+    return Math.round(v * 1000) / 1000;
+}

package/dist/vascend/context-retriever.d.ts

@@ -0,0 +1,22 @@
+import { ContextSearchIndex } from "./context-search-index.js";
+import type { ContextCandidate } from "./context-candidate.js";
+import { type SynonymIndex } from "./lexical-search.js";
+export interface RetrieveOptions {
+    readonly index?: ContextSearchIndex;
+    /** Reference path for rollback and ranking equivalence checks. */
+    readonly legacy?: boolean;
+    readonly query: string;
+    readonly limit?: number;
+    readonly expandLinks?: boolean;
+    readonly minScore?: number;
+    readonly synonyms?: SynonymIndex;
+    readonly dropSuperseded?: boolean;
+}
+export interface RetrievedCandidate {
+    readonly candidate: ContextCandidate;
+    readonly lexScore: number;
+    readonly graphScore: number;
+    readonly retrievalScore: number;
+    readonly viaLink: boolean;
+}
+export declare function retrieve(pool: readonly ContextCandidate[], opts: RetrieveOptions): readonly RetrievedCandidate[];