@vascend/talos 0.1.0

package/dist/vascend/context-feedback-loop.js

@@ -0,0 +1,204 @@
+// Context Feedback Loop (metodo Danilov, Memory OS) -- L3: l'auto-miglioramento.
+//
+// Questo e' "l'auto-miglioramento che PER DAVVERO funziona": non un suggerimento
+// testuale, ma un ANELLO CHIUSO e deterministico che migliora misurabilmente la
+// qualita' del contesto compilato regolando da solo lo scorer.
+//
+//   config0 -> compile -> metrics -> qualityScore
+//                  |                      |
+//                  v                      v
+//             autotuneStep <----- diagnose(metrics)
+//                  |
+//                  v
+//   config1 -> compile -> metrics -> qualityScore (>= precedente)  ... finche' converge
+//
+// Garanzie:
+//   - DETERMINISMO: a parita' di compile() e config iniziale, stesso esito.
+//   - MONOTONIA: l'anello tiene la MIGLIORE config vista; non regredisce mai.
+//   - CONVERGENZA: si ferma quando nessuna correzione e' proposta o il guadagno
+//     scende sotto minGain, oppure dopo maxRounds (anti-loop).
+//
+// Modulo PURO: nessun side-effect proprio. Il side-effect (compilare con gli
+// store reali) e' iniettato come funzione `compile`. Per i test si passa una
+// compile finta; per il runtime si usa runContextFeedbackLoop con compileContext.
+import { autotuneStep, qualityScore, hasConverged, formatAdjustments, DEFAULT_CONFIG, DEFAULT_TARGETS, } from "./context-autotuner.js";
+import { compileContext } from "./context-window-compiler.js";
+import { loadContextStoreSnapshot } from "./context-snapshot.js";
+import { TunerBaselineStore, DEFAULT_BASELINE_SCOPE, } from "./tuner-baseline-store.js";
+import { exploreContextPatterns, } from "./context-pattern-explorer.js";
+// Esegue l'anello su una compile iniettata. CUORE del modulo: puro rispetto a
+// `compile` (che incapsula ogni side-effect). Ritorna la config migliore.
+export function runFeedbackLoop(compile, opts = {}) {
+    const targets = opts.targets ?? DEFAULT_TARGETS;
+    const maxRounds = opts.maxRounds && opts.maxRounds > 0 ? opts.maxRounds : 8;
+    const minGain = typeof opts.minGain === "number" ? opts.minGain : 1;
+    let config = opts.config ?? DEFAULT_CONFIG;
+    const trajectory = [];
+    // Misura di partenza.
+    let metrics = compile(config);
+    let score = qualityScore(metrics, targets);
+    const initialScore = score;
+    let bestConfig = config;
+    let bestScore = score;
+    let converged = false;
+    let round = 0;
+    for (; round < maxRounds; round++) {
+        // Diagnosi della config corrente -> proposta di nuova config.
+        const step = autotuneStep(config, metrics, targets);
+        trajectory.push({ round, config, metrics, score, adjustments: step.adjustments });
+        // Nessuna correzione proposta = convergenza strutturale.
+        if (step.adjustments.length === 0) {
+            converged = true;
+            break;
+        }
+        // Prova la nuova config.
+        const nextMetrics = compile(step.config);
+        const nextScore = qualityScore(nextMetrics, targets);
+        const gain = nextScore - score;
+        // MONOTONIA: tieni sempre la config migliore vista, mai regredire.
+        if (nextScore > bestScore) {
+            bestScore = nextScore;
+            bestConfig = step.config;
+        }
+        // CONVERGENZA: guadagno sotto soglia -> ci fermiamo.
+        if (hasConverged(step.adjustments, gain, minGain)) {
+            converged = true;
+            // Registra l'ultimo stato provato per trasparenza.
+            trajectory.push({ round: round + 1, config: step.config, metrics: nextMetrics, score: nextScore, adjustments: [] });
+            break;
+        }
+        // Avanza l'anello.
+        config = step.config;
+        metrics = nextMetrics;
+        score = nextScore;
+    }
+    return {
+        bestConfig,
+        bestScore,
+        initialScore,
+        improved: bestScore > initialScore,
+        converged,
+        rounds: trajectory.length,
+        trajectory,
+    };
+}
+// --- wiring sul compiler reale ----------------------------------------------
+// Esegue l'anello compilando DAVVERO il contesto dagli store: per ogni config
+// chiama compileContext e ne estrae le metriche. Ritorna sia l'esito dell'anello
+// sia il contesto compilato FINALE con la config migliore (pronto da usare).
+export function runContextFeedbackLoop(input, opts = {}) {
+    // now fisso per determinismo dell'intero anello (freshness stabile fra round).
+    const now = input.now ?? Date.now();
+    // Lo snapshot degli store e' condiviso da TUTTE le compile dell'anello: fra i
+    // round cambiano solo pesi e soglie dello scorer, mentre pool di candidati,
+    // Memory Packet e ranking lessicale sono per costruzione identici. Senza
+    // questo, ogni round rileggeva l'intero Memory OS da disco.
+    const base = { ...input, now, snapshot: snapshotFor(input) };
+    const compile = (config) => compileContext({ ...base, weights: config.weights, thresholds: config.thresholds }).metrics;
+    const loop = runFeedbackLoop(compile, opts);
+    // Compila una volta in piu' con la config migliore per restituire il pack.
+    const compiled = compileContext({
+        ...base,
+        weights: loop.bestConfig.weights,
+        thresholds: loop.bestConfig.thresholds,
+    });
+    return { loop, compiled };
+}
+// Snapshot degli store per un input di compilazione: rispetta quello passato
+// dal chiamante (un turno che compila piu' volte lo condivide) e altrimenti lo
+// materializza una volta per l'intero anello.
+function snapshotFor(input) {
+    return input.snapshot ?? loadContextStoreSnapshot({
+        sessionDir: input.sessionDir,
+        scopeId: input.scopeId,
+        ...(input.projectKey ? { projectKey: input.projectKey } : {}),
+    });
+}
+// L'auto-miglioramento che RICORDA: invece di ripartire dai default, carica la
+// baseline appresa come config iniziale, esegue l'anello, e SE migliora salva la
+// bestConfig fondendola nella baseline via EMA. Cosi' ogni turno/sessione parte
+// dall'architettura gia' ottimizzata e l'apprendimento e' CUMULATIVO.
+//
+//   baseline.startConfig -> runContextFeedbackLoop -> baseline.observe(best)
+//
+// Ritorna l'esito dell'anello, il contesto compilato finale e la baseline
+// aggiornata (quella nuova se ha osservato, quella corrente in dry-run).
+export function runLearningFeedbackLoop(input, opts) {
+    const scope = (opts.scope || DEFAULT_BASELINE_SCOPE).trim() || DEFAULT_BASELINE_SCOPE;
+    const store = TunerBaselineStore.open(opts.dir, opts.storeId);
+    // Punto di partenza = config appresa (o default se mai osservato).
+    const startConfig = store.startConfig(scope);
+    // Esegue l'anello partendo dalla baseline appresa.
+    const { loop, compiled } = runContextFeedbackLoop(input, { ...opts, config: startConfig });
+    // Incorpora l'osservazione nella baseline (monotonia morbida via EMA):
+    // una bestConfig migliore attira la baseline; una peggiore non la sposta.
+    let baseline = store.get(scope);
+    if (opts.persist !== false) {
+        baseline = store.observe(scope, {
+            config: loop.bestConfig,
+            score: loop.bestScore,
+            initialScore: loop.initialScore,
+        });
+    }
+    return { loop, compiled, baseline };
+}
+// L'AUTO-MIGLIORAMENTO DEEP: non solo il KPI vincente, ma la mappa completa.
+// Esplora in profondita' lo spazio di config compilando DAVVERO dagli store, in
+// parallelo su tutti i pattern (preset + perturbazioni + greedy + restart),
+// classifica le migliorie, adotta la best e la fonde nella baseline appresa (cosi'
+// il prossimo turno parte gia' dall'architettura migliorata). Ritorna la classifica
+// completa, il pack compilato con la best, e la baseline aggiornata.
+//
+//   baseline.startConfig -> exploreContextPatterns(parallelo) -> ranking
+//        best -> compile(pack)  +  baseline.observe(best)
+export async function runDeepSelfImprove(input, opts) {
+    const now = input.now ?? Date.now();
+    const scope = (opts.scope || DEFAULT_BASELINE_SCOPE).trim() || DEFAULT_BASELINE_SCOPE;
+    const store = TunerBaselineStore.open(opts.dir, opts.storeId);
+    // Parti dalla config gia' appresa: l'esplorazione deep scava ATTORNO e LONTANO
+    // da essa, cosi' l'apprendimento cumulativo si combina con la ricerca larga.
+    const startConfig = store.startConfig(scope);
+    // Compile reale (sincrona): data una config, compila e ritorna le metriche.
+    // Usata sia per i punti greedy/restart sia per la valutazione dei pattern.
+    // Snapshot condiviso: l'esplorazione compila decine di volte, e leggere gli
+    // store una volta per pattern moltiplicava l'I/O per il numero di pattern.
+    const base = { ...input, now, snapshot: snapshotFor(input) };
+    const compileMetrics = (config) => compileContext({ ...base, weights: config.weights, thresholds: config.thresholds }).metrics;
+    // ESPLORAZIONE DEEP IN PARALLELO. La compile e' sincrona qui: la passiamo sia
+    // come compile principale sia come compileSyncForGreedy.
+    const ranking = await exploreContextPatterns(compileMetrics, {
+        ...opts,
+        baseConfig: startConfig,
+        compileSyncForGreedy: compileMetrics,
+    });
+    // Adotta la BEST della classifica e compila il pack finale con essa.
+    const best = ranking.best.config;
+    const compiled = compileContext({ ...base, weights: best.weights, thresholds: best.thresholds });
+    // Fonde la best nella baseline appresa (EMA): il prossimo turno parte da qui.
+    let baseline = store.get(scope);
+    if (opts.persist !== false) {
+        baseline = store.observe(scope, {
+            config: best,
+            score: ranking.best.score,
+            initialScore: ranking.baselineScore,
+        });
+    }
+    return { ranking, compiled, baseline };
+}
+// --- diagnostica -------------------------------------------------------------
+// Formatta l'esito dell'anello come blocco Danilov per log/TUI.
+export function formatLoopResult(result) {
+    const lines = [
+        "[CONTEXT_FEEDBACK_LOOP]",
+        `@anello: round=${result.rounds}, converged=${result.converged}`,
+        `@qualita: iniziale=${result.initialScore} -> migliore=${result.bestScore} (${result.improved ? "MIGLIORATO" : "stabile"})`,
+    ];
+    for (const step of result.trajectory) {
+        lines.push(`@step[${step.round}]: score=${step.score}, utility=${step.metrics.contextUtility}, stale=${step.metrics.staleMemoryRate}, coverage=${step.metrics.evidenceCoverage}`);
+        const adj = formatAdjustments(step.adjustments);
+        if (step.adjustments.length)
+            lines.push("  " + adj.split("\n").join("\n  "));
+    }
+    lines.push("OUTPUT: usa bestConfig come pesi/soglie dello scorer per i prossimi turni.");
+    return lines.join("\n");
+}

package/dist/vascend/context-learning-identity.d.ts

@@ -0,0 +1,4 @@
+export declare function contextLearningIdentity(cwd: string, env?: NodeJS.ProcessEnv): {
+    storeId: string;
+    scope: string;
+};

package/dist/vascend/context-learning-identity.js

@@ -0,0 +1,8 @@
+import { basename } from "node:path";
+import { contextProjectKey } from "./context-fabric.js";
+export function contextLearningIdentity(cwd, env = process.env) {
+    return {
+        storeId: "project-" + contextProjectKey(cwd),
+        scope: env["TALOS_CTX_LEARN_SCOPE"]?.trim() || basename(cwd) || "memory-os",
+    };
+}

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

@@ -0,0 +1,14 @@
+import type { ContextCandidate } from "./context-candidate.js";
+export interface CandidateNeighbor {
+    readonly candidate: ContextCandidate;
+    readonly weight: number;
+}
+/** Explicit and textual references are indexed once, not found by scanning every node per hop. */
+export declare class CandidateLinks {
+    private readonly byId;
+    private readonly edges;
+    private readonly castles;
+    constructor(candidates: readonly ContextCandidate[]);
+    neighbors(id: string): readonly CandidateNeighbor[];
+    private link;
+}

package/dist/vascend/context-links.js

@@ -0,0 +1,83 @@
+/** Explicit and textual references are indexed once, not found by scanning every node per hop. */
+export class CandidateLinks {
+    byId;
+    edges = new Map();
+    castles = new Map();
+    constructor(candidates) {
+        this.byId = new Map(candidates.map((candidate) => [candidate.id, candidate]));
+        const nodes = [{ next: new Map(), fail: 0, ids: [] }];
+        for (const candidate of candidates) {
+            let state = 0;
+            const key = candidate.id.toLowerCase();
+            for (let i = 0; i < key.length; i++) {
+                const ch = key[i];
+                let next = nodes[state].next.get(ch);
+                if (next === undefined) {
+                    next = nodes.length;
+                    nodes[state].next.set(ch, next);
+                    nodes.push({ next: new Map(), fail: 0, ids: [] });
+                }
+                state = next;
+            }
+            if (candidate.id)
+                nodes[state].ids.push(candidate.id);
+            const castle = prefix(candidate.id);
+            if (castle) {
+                const group = this.castles.get(castle) ?? [];
+                group.push(candidate.id);
+                this.castles.set(castle, group);
+            }
+            for (const id of candidate.links)
+                this.link(candidate.id, id, 0.68);
+        }
+        const queue = [...nodes[0].next.values()];
+        for (let i = 0; i < queue.length; i++) {
+            const state = queue[i];
+            for (const [ch, next] of nodes[state].next) {
+                let fail = nodes[state].fail;
+                while (fail && !nodes[fail].next.has(ch))
+                    fail = nodes[fail].fail;
+                nodes[next].fail = nodes[fail].next.get(ch) ?? 0;
+                nodes[next].ids.push(...nodes[nodes[next].fail].ids);
+                queue.push(next);
+            }
+        }
+        for (const candidate of candidates) {
+            const text = (candidate.summary + " " + candidate.body + " " + candidate.terms.join(" ")).toLowerCase();
+            let state = 0;
+            for (let i = 0; i < text.length; i++) {
+                const ch = text[i];
+                while (state && !nodes[state].next.has(ch))
+                    state = nodes[state].fail;
+                state = nodes[state].next.get(ch) ?? 0;
+                for (const id of nodes[state].ids) {
+                    const start = i - id.length + 1;
+                    if (!/[a-z0-9_]/i.test(text[start - 1] ?? "") && !/[a-z0-9_]/i.test(text[i + 1] ?? "")) {
+                        this.link(candidate.id, id, 0.52);
+                    }
+                }
+            }
+        }
+    }
+    neighbors(id) {
+        const weights = new Map(this.edges.get(id));
+        for (const neighbor of this.castles.get(prefix(id)) ?? []) {
+            if (neighbor !== id && !weights.has(neighbor))
+                weights.set(neighbor, 0.18);
+        }
+        return [...weights].flatMap(([key, weight]) => {
+            const candidate = this.byId.get(key);
+            return candidate ? [{ candidate, weight }] : [];
+        });
+    }
+    link(a, b, weight) {
+        if (a === b || !this.byId.has(a) || !this.byId.has(b))
+            return;
+        for (const [from, to] of [[a, b], [b, a]]) {
+            const edges = this.edges.get(from) ?? new Map();
+            edges.set(to, Math.max(edges.get(to) ?? 0, weight));
+            this.edges.set(from, edges);
+        }
+    }
+}
+function prefix(id) { return id.includes("/") ? id.slice(0, id.indexOf("/")) : ""; }

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

@@ -0,0 +1,22 @@
+import type { ContextCandidate } from "./context-candidate.js";
+export type LintSeverity = "info" | "warn" | "error";
+export interface LintFinding {
+    readonly code: "duplicate" | "stale" | "missing_decision" | "missing_vision" | "budget_exceeded" | "conflict";
+    readonly severity: LintSeverity;
+    readonly message: string;
+    readonly ids?: readonly string[];
+}
+export interface LintInput {
+    readonly selected: readonly ContextCandidate[];
+    readonly tokenBudget?: number;
+    readonly renderedTokens?: number;
+    readonly hasVision?: boolean;
+    readonly hasActiveDecisions?: boolean;
+}
+export interface LintReport {
+    readonly findings: readonly LintFinding[];
+    readonly cleaned: readonly ContextCandidate[];
+    readonly ok: boolean;
+}
+export declare function lintContext(input: LintInput): LintReport;
+export declare function formatLintReport(report: LintReport): string;

package/dist/vascend/context-lint.js

@@ -0,0 +1,91 @@
+// Context Lint (metodo Danilov, Memory OS).
+//
+// Controllo qualita' del Prompt Pack PRIMA della chiamata al provider. Combatte
+// il context rot rilevando: duplicati, memorie stale/superseded, decisioni
+// attive mancanti, Vision assente, budget superato e contraddizioni. Puo'
+// CORREGGERE in automatico (dedup, drop stale) e segnalare il resto.
+//
+// Modulo PURO e deterministico: opera su candidati gia' selezionati + segnali
+// di stato, ritorna un report + il set ripulito.
+import { buildSupersessionGraph } from "./supersession-graph.js";
+import { estimateCandidateTokens } from "./context-candidate.js";
+// Esegue il lint e la pulizia automatica. Deterministico.
+export function lintContext(input) {
+    const findings = [];
+    const selected = input.selected;
+    // 1) STALE prima della deduplica: una vecchia copia con lo stesso summary
+    // non deve eliminare quella attiva prima di essere scartata a sua volta.
+    const graph = buildSupersessionGraph(selected);
+    const staleIds = [];
+    const active = selected.filter((candidate) => {
+        const stale = candidate.status !== "active" || graph.superseded.has(candidate.id);
+        if (stale)
+            staleIds.push(candidate.id);
+        return !stale;
+    });
+    if (staleIds.length) {
+        findings.push({ code: "stale", severity: "warn", message: `rimosse ${staleIds.length} memorie obsolete/superseded`, ids: staleIds });
+    }
+    // 2) DEDUP: stessa fonte/tipo e stesso contenuto. Summary uguali possono
+    // contenere prove diverse nel body; il codice preserva anche il case.
+    const seenId = new Set();
+    const seenContent = new Set();
+    const dedupDropped = [];
+    const cleaned = [];
+    for (const c of active) {
+        const contentKey = c.subject || c.summary || c.body
+            ? JSON.stringify([c.kind, c.domain, c.subject, c.summary, c.body]) : "";
+        if (seenId.has(c.id) || (contentKey && seenContent.has(contentKey))) {
+            dedupDropped.push(c.id);
+            continue;
+        }
+        seenId.add(c.id);
+        if (contentKey)
+            seenContent.add(contentKey);
+        cleaned.push(c);
+    }
+    if (dedupDropped.length) {
+        findings.push({ code: "duplicate", severity: "info", message: `rimossi ${dedupDropped.length} duplicati`, ids: dedupDropped });
+    }
+    // 3) CONFLICT: candidati che dichiarano supersededBy verso un id ancora
+    //    presente -> contraddizione residua (non risolta dal drop).
+    const presentIds = new Set(cleaned.map((c) => c.id));
+    const conflicts = cleaned.filter((c) => c.supersededBy && presentIds.has(c.supersededBy)).map((c) => c.id);
+    if (conflicts.length) {
+        findings.push({ code: "conflict", severity: "warn", message: `contraddizioni residue (supersededBy presente)`, ids: conflicts });
+    }
+    // 4) MISSING VISION.
+    if (input.hasVision === false) {
+        findings.push({ code: "missing_vision", severity: "warn", message: "Vision assente: rischio drift dalla stella polare" });
+    }
+    // 5) MISSING DECISIONS.
+    if (input.hasActiveDecisions && !cleaned.some((c) => c.kind === "decision")) {
+        findings.push({ code: "missing_decision", severity: "warn", message: "decisioni attive non incluse nel contesto" });
+    }
+    // 6) BUDGET.
+    if (input.tokenBudget !== undefined && input.tokenBudget >= 0) {
+        const used = input.renderedTokens ?? cleaned.reduce((sum, c) => sum + estimateCandidateTokens(c, "body"), 0);
+        if (used > input.tokenBudget) {
+            findings.push({
+                code: "budget_exceeded",
+                severity: "error",
+                message: `budget superato: ${used} > ${input.tokenBudget} token`,
+            });
+        }
+    }
+    const ok = !findings.some((f) => f.severity === "error");
+    return { findings, cleaned, ok };
+}
+// Formatta il report del lint come blocco diagnostico (per log/debug, non per
+// il prompt). Deterministico.
+export function formatLintReport(report) {
+    if (!report.findings.length)
+        return "[CONTEXT_LINT] ok: nessun problema";
+    const lines = ["[CONTEXT_LINT]"];
+    for (const f of report.findings) {
+        const ids = f.ids?.length ? ` [${f.ids.join(", ")}]` : "";
+        lines.push(`@${f.code}[${f.severity}]: ${f.message}${ids}`);
+    }
+    lines.push(`OUTPUT: ${report.ok ? "pack approvato" : "pack DA CORREGGERE (errori presenti)"}`);
+    return lines.join("\n");
+}

package/dist/vascend/context-market-selection.d.ts

@@ -0,0 +1,17 @@
+import type { ContextScore } from "./context-candidate.js";
+import { type ContextCapsule } from "./context-capsule.js";
+import { type MarketResult } from "./token-market.js";
+export interface MarketSelectionInput {
+    readonly scored: readonly ContextScore[];
+    readonly retrievalScores?: ReadonlyMap<string, number>;
+    readonly lexScores?: ReadonlyMap<string, number>;
+    readonly evidenceBudget: number;
+    readonly memoryBudget: number;
+    readonly now: number;
+}
+export interface MarketSelection {
+    readonly evidence: readonly ContextCapsule[];
+    readonly memory: readonly ContextCapsule[];
+    readonly market: MarketResult;
+}
+export declare function selectWithMarket(input: MarketSelectionInput): MarketSelection;

package/dist/vascend/context-market-selection.js

@@ -0,0 +1,50 @@
+import { capsuleFromCandidate, withExpansion } from "./context-capsule.js";
+import { renderCapsules, tokensAtLevel } from "./expansion-levels.js";
+import { estimateTokens } from "./budget-allocator.js";
+import { runTokenMarket } from "./token-market.js";
+export function selectWithMarket(input) {
+    const eligible = input.scored.filter((score) => score.tier !== "low");
+    const maxScore = eligible.reduce((max, score) => Math.max(max, score.score), 0);
+    const novelty = new Map(eligible.map((score) => [score.candidate.id, score.factors.novelty]));
+    const capsules = eligible.map((score) => capsuleFromCandidate(score.candidate, {
+        now: input.now,
+        ...(maxScore > 0 ? { utility: Math.max(0, score.score) / maxScore } : {}),
+    }));
+    const proposed = runTokenMarket(capsules, {
+        tokenBudget: Math.max(0, input.evidenceBudget) + Math.max(0, input.memoryBudget),
+        ...((input.retrievalScores?.size || input.lexScores?.size)
+            ? { relevance: input.retrievalScores ?? input.lexScores } : {}),
+        novelty,
+    });
+    const evidence = [];
+    const memory = [];
+    const admitted = [];
+    const dropped = [...proposed.dropped];
+    for (const allocation of proposed.admitted) {
+        if (allocation.level === "drop")
+            continue;
+        let placed = false;
+        for (let level = allocation.level; level >= 0; level -= 1) {
+            const expansion = level;
+            const capsule = withExpansion(allocation.capsule, expansion);
+            const zone = level >= 3 ? evidence : memory;
+            const budget = level >= 3 ? input.evidenceBudget : input.memoryBudget;
+            if (estimateTokens(renderCapsules([...zone, capsule])) > budget)
+                continue;
+            zone.push(capsule);
+            admitted.push({ ...allocation, capsule, level: expansion, tokensUsed: tokensAtLevel(capsule, expansion) });
+            placed = true;
+            break;
+        }
+        if (!placed)
+            dropped.push({ ...allocation, level: "drop", tokensUsed: 0 });
+    }
+    return {
+        evidence,
+        memory,
+        market: {
+            admitted, dropped, tokenBudget: proposed.tokenBudget,
+            tokensUsed: estimateTokens(renderCapsules(evidence)) + estimateTokens(renderCapsules(memory)),
+        },
+    };
+}

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

@@ -0,0 +1,25 @@
+import type { ContextScore } from "./context-candidate.js";
+import type { LintReport } from "./context-lint.js";
+export interface ContextMetrics {
+    readonly contextUtility: number;
+    readonly staleMemoryRate: number;
+    readonly evidenceCoverage: number;
+    readonly decisionConsistency: boolean;
+    readonly counts: {
+        readonly total: number;
+        readonly high: number;
+        readonly mid: number;
+        readonly low: number;
+        readonly stale: number;
+        readonly packTokens: number;
+    };
+}
+export interface MetricsInput {
+    readonly scored: readonly ContextScore[];
+    readonly pack: string;
+    readonly report: LintReport;
+    readonly includedIds?: ReadonlySet<string>;
+    readonly evidenceIds?: ReadonlySet<string>;
+}
+export declare function computeContextMetrics(input: MetricsInput): ContextMetrics;
+export declare function formatContextMetrics(m: ContextMetrics): string;

package/dist/vascend/context-metrics.js

@@ -0,0 +1,57 @@
+// Context Metrics (metodo Danilov, Memory OS).
+//
+// "Non basta dire che e' migliore: bisogna misurarlo." Questo modulo calcola le
+// metriche chiave del documento talos-context su un contesto compilato, per
+// benchmark interni e diagnostica del Context Window Compiler.
+//
+//   context_utility    = informazioni utili (tier high/mid) per 1k token
+//   stale_memory_rate  = quota di candidati obsoleti/superseded entrati
+//   evidence_coverage  = quota di risposte sul passato coperte da evidenze
+//   decision_consistency = nessun superseded incluso tra le decisioni
+//
+// Modulo PURO e deterministico: opera su ContextScore + report di lint.
+import { estimateTokens } from "./budget-allocator.js";
+// Calcola le metriche del contesto compilato. Deterministico.
+export function computeContextMetrics(input) {
+    const scored = input.scored;
+    const total = scored.length;
+    const admitted = input.includedIds
+        ? scored.filter((score) => input.includedIds?.has(score.candidate.id))
+        : scored.filter((score) => score.tier !== "low");
+    const high = admitted.filter((s) => s.tier === "high").length;
+    const mid = admitted.filter((s) => s.tier === "mid").length;
+    const low = Math.max(0, total - high - mid);
+    const useful = high + mid;
+    const packTokens = estimateTokens(input.pack);
+    const contextUtility = packTokens ? round((useful / packTokens) * 1000) : 0;
+    // Stale: candidati inclusi (non low) che risultano non-active.
+    const included = admitted;
+    const stale = included.filter((s) => s.candidate.status !== "active" || s.candidate.supersededBy).length;
+    const staleMemoryRate = included.length ? round(stale / included.length) : 0;
+    const evidenceCount = input.evidenceIds
+        ? admitted.filter((score) => input.evidenceIds?.has(score.candidate.id)).length
+        : high;
+    const evidenceCoverage = admitted.length ? round(evidenceCount / admitted.length) : 0;
+    const decisionConsistency = !included.some((s) => s.candidate.kind === "decision" && (s.candidate.status !== "active" || s.candidate.supersededBy));
+    return {
+        contextUtility,
+        staleMemoryRate,
+        evidenceCoverage,
+        decisionConsistency,
+        counts: { total, high, mid, low, stale, packTokens },
+    };
+}
+// Formatta le metriche come blocco Danilov (diagnostica/log).
+export function formatContextMetrics(m) {
+    return [
+        "[CONTEXT_METRICS]",
+        `@metrica[context_utility]: ${m.contextUtility} utili/1k_token`,
+        `@metrica[stale_memory_rate]: ${m.staleMemoryRate}`,
+        `@metrica[evidence_coverage]: ${m.evidenceCoverage}`,
+        `@metrica[decision_consistency]: ${m.decisionConsistency}`,
+        `@counts: total=${m.counts.total}, high=${m.counts.high}, mid=${m.counts.mid}, low=${m.counts.low}, stale=${m.counts.stale}, pack_tokens=${m.counts.packTokens}`,
+    ].join("\n");
+}
+function round(v) {
+    return Math.round(v * 1000) / 1000;
+}

package/dist/vascend/context-pack-render.d.ts

@@ -0,0 +1,16 @@
+import type { ContextCandidate } from "./context-candidate.js";
+export interface RenderedSelection<T> {
+    readonly text: string;
+    readonly included: readonly T[];
+    readonly excluded: readonly T[];
+}
+export declare function packRendered<T>(items: readonly T[], render: (item: T) => string, maxTokens: number, envelope?: {
+    readonly before?: string;
+    readonly after?: string;
+}): RenderedSelection<T>;
+export declare function remainingTokens(budget: number, prefix: string): number;
+export declare function renderControlLane(candidates: readonly ContextCandidate[], tokenBudget: number): RenderedSelection<ContextCandidate>;
+export declare function renderHandle(candidate: ContextCandidate): string;
+export declare const HANDLE_GUIDE = "HANDLES (usa recall <id> per espandere quando serve il dettaglio):";
+export declare function renderEvidence(candidate: ContextCandidate): string;
+export declare function joinBlocks(...blocks: readonly string[]): string;

package/dist/vascend/context-pack-render.js

@@ -0,0 +1,52 @@
+import { estimateTokens } from "./budget-allocator.js";
+export function packRendered(items, render, maxTokens, envelope = {}) {
+    const included = [];
+    const excluded = [];
+    const blocks = [];
+    let text = "";
+    for (const item of items) {
+        const block = render(item).trim();
+        const next = joinBlocks(envelope.before ?? "", ...blocks, block, envelope.after ?? "");
+        if (block && estimateTokens(next) <= maxTokens) {
+            blocks.push(block);
+            included.push(item);
+            text = next;
+        }
+        else {
+            excluded.push(item);
+        }
+    }
+    return { text, included, excluded };
+}
+export function remainingTokens(budget, prefix) {
+    return Math.max(0, budget - (prefix ? estimateTokens(`${prefix}\n\n`) : 0));
+}
+export function renderControlLane(candidates, tokenBudget) {
+    return packRendered(candidates, (candidate) => `@control[${candidate.id}/${candidate.kind}]: ${oneLine(candidate.summary || candidate.subject, 180)}`, tokenBudget, {
+        before: "[CONTROL_LANE]\nFonte autoritativa: non dichiarare completati task aperti e non contraddire decisioni attive.",
+        after: "[/CONTROL_LANE]",
+    });
+}
+export function renderHandle(candidate) {
+    return `@handle[${candidate.id}]: kind=${candidate.kind}, "${oneLine(candidate.summary, 90)}"`;
+}
+export const HANDLE_GUIDE = "HANDLES (usa recall <id> per espandere quando serve il dettaglio):";
+export function renderEvidence(candidate) {
+    return [
+        `[EVIDENCE:${candidate.id}]`,
+        `domain=${candidate.domain}`,
+        `kind=${candidate.kind}`,
+        `subject=${oneLine(candidate.subject, 100)}`,
+        `summary="${oneLine(candidate.summary, 160)}"`,
+        `confidence=${candidate.trust}`,
+        `supersededBy=${candidate.supersededBy ?? "null"}`,
+        candidate.body ? `body="${oneLine(candidate.body, 400)}"` : "",
+    ].filter(Boolean).join("\n");
+}
+function oneLine(value, max) {
+    const text = value.replace(/\s+/g, " ").trim().replace(/"/g, "'");
+    return text.length > max ? text.slice(0, max - 1).trimEnd() + "…" : text;
+}
+export function joinBlocks(...blocks) {
+    return blocks.map((block) => block.trim()).filter(Boolean).join("\n\n");
+}