@vascend/talos 0.1.0

package/dist/vascend/completeness.js

@@ -0,0 +1,90 @@
+export function completenessEnabled(env) {
+    const v = (env["TALOS_COMPLETENESS"] ?? "").trim().toLowerCase();
+    return !(v === "0" || v === "off" || v === "false" || v === "no");
+}
+// Quante volte al massimo svegliare l'agente per completare (anti-loop).
+export function completenessRounds(env) {
+    const n = Number(env["TALOS_COMPLETENESS_ROUNDS"]);
+    return Number.isInteger(n) && n >= 0 ? n : 2;
+}
+const CRITIC_SYSTEM = `# Critico di completezza
+INDICE
+1 = goal
+2 = consegna
+3 = mancante
+
+DEFINIZIONI
+@goal[reale]: l'obiettivo VERO dell'utente, non il piano svolto
+@consegna[criterio]: completa = funzionante e utilizzabile come chiesto (es. una SaaS: dati, auth, CRUD, UI, flussi base)
+@mancante[regola]: elenca SOLO pezzi ESSENZIALI assenti; niente perfezionismo, niente nice-to-have
+@rigore[bilancia]: se la consegna soddisfa il goal nella sostanza, complete=true
+
+RELAZIONI
+@R1: @goal[reale] -> @consegna[criterio]  [ misura la consegna sul goal vero ]
+@R2: @consegna[criterio] -> @mancante[regola]  [ elenca solo l'essenziale assente ]
+
+OUTPUT: SOLO JSON {"complete": bool, "missing": [stringhe brevi]}. Niente prosa, niente markdown.`;
+export async function judgeCompleteness(opts) {
+    const { harness, goal, evidence, signal } = opts;
+    const resolved = harness.providers.resolve(harness.config.model);
+    if (!resolved)
+        return unknownVerdict("provider del critico non disponibile");
+    const user = `GOAL dell'utente:\n${goal}\n\nLAVORO SVOLTO (sintesi + attivita):\n${evidence}\n\n` +
+        `Manca qualcosa di ESSENZIALE per consegnare il goal in modo completo e funzionante? ` +
+        `Rispondi SOLO JSON {"complete": bool, "missing": [...]}.`;
+    try {
+        const res = await resolved.provider.complete({
+            system: CRITIC_SYSTEM,
+            messages: [{ role: "user", content: [{ type: "text", text: user }] }],
+            tools: [],
+            model: resolved.modelId,
+            maxTokens: harness.config.maxTokens,
+            signal,
+            sessionId: `completeness-${harness.session.id}`,
+        });
+        return parseVerdict(res.text);
+    }
+    catch (error) {
+        return unknownVerdict(`verifica non riuscita: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function parseVerdict(text) {
+    const m = /\{[\s\S]*\}/.exec(text);
+    if (!m)
+        return unknownVerdict("risposta del critico non strutturata");
+    try {
+        const raw = JSON.parse(m[0]);
+        const missing = Array.isArray(raw.missing) ? raw.missing.map(String).map((s) => s.trim()).filter(Boolean).slice(0, 12) : [];
+        if (raw.complete === true && missing.length === 0)
+            return { complete: true, missing: [] };
+        if (raw.complete === false) {
+            return { complete: false, missing: missing.length ? missing : ["criteri di consegna non dimostrati"] };
+        }
+        return unknownVerdict("il critico non ha espresso un verdetto booleano");
+    }
+    catch {
+        return unknownVerdict("JSON del critico non valido");
+    }
+}
+function unknownVerdict(reason) {
+    return { complete: false, missing: [], uncertain: true, reason };
+}
+// Steer in notazione Danilov per far continuare l'agente sui pezzi mancanti.
+export function buildCompletenessSteer(goal, missing) {
+    return `[VASCEND_COMPLETEZZA]
+INDICE
+1 = goal
+2 = mancante
+3 = azione
+
+DEFINIZIONI
+@goal[reale]: "${goal.replace(/"/g, "'").slice(0, 200)}"
+@mancante[pezzi]: ${missing.map((m, i) => `(${i + 1}) ${m}`).join(" ; ")}
+@azione[continua]: NON ti fermi al piano gia' fatto; il goal non e' "ho creato i gruppi" ma "ho consegnato la cosa completa"
+
+RELAZIONI
+@R1: @mancante[pezzi] -> @azione[continua]  [ pianifica e COSTRUISCI i pezzi mancanti ]
+@R2: @azione[continua] -> @goal[reale]  [ finche' la consegna soddisfa il goal vero ]
+
+OUTPUT: crea altri gruppi/attivita e realizza i pezzi mancanti elencati, poi illuminali. Vai fino a una consegna completa e funzionante, non fermarti al primo piano.`;
+}

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

@@ -0,0 +1,45 @@
+import type { ScoreWeights, TierThresholds } from "./context-scorer.js";
+import type { ContextMetrics } from "./context-metrics.js";
+export interface QualityTargets {
+    readonly minUtility: number;
+    readonly maxStaleRate: number;
+    readonly minEvidenceCoverage: number;
+    readonly maxEvidenceCoverage: number;
+}
+export declare const DEFAULT_TARGETS: QualityTargets;
+export interface TuneConfig {
+    readonly weights: ScoreWeights;
+    readonly thresholds: TierThresholds;
+}
+export declare const DEFAULT_CONFIG: TuneConfig;
+export declare const WEIGHT_BOUNDS: Readonly<Record<keyof ScoreWeights, readonly [number, number]>>;
+export declare const HIGH_BOUNDS: readonly [number, number];
+export declare const MID_BOUNDS: readonly [number, number];
+export interface TuneAdjustment {
+    readonly lever: keyof ScoreWeights | "thresholdHigh" | "thresholdMid";
+    readonly delta: number;
+    readonly reason: string;
+}
+export declare function diagnose(metrics: ContextMetrics, targets?: QualityTargets): TuneAdjustment[];
+export declare function applyAdjustments(config: TuneConfig, adjustments: readonly TuneAdjustment[]): TuneConfig;
+export declare function autotuneStep(config: TuneConfig, metrics: ContextMetrics, targets?: QualityTargets): {
+    readonly config: TuneConfig;
+    readonly adjustments: readonly TuneAdjustment[];
+};
+export declare function qualityScore(metrics: ContextMetrics, targets?: QualityTargets): number;
+export declare function hasConverged(adjustments: readonly TuneAdjustment[], scoreDelta: number, minDelta?: number): boolean;
+export type CompileMetrics = (config: TuneConfig) => ContextMetrics;
+export interface GreedyOptions {
+    readonly config?: TuneConfig;
+    readonly targets?: QualityTargets;
+    readonly maxRounds?: number;
+    readonly minGain?: number;
+}
+export interface GreedyResult {
+    readonly bestConfig: TuneConfig;
+    readonly bestScore: number;
+    readonly initialScore: number;
+    readonly rounds: number;
+}
+export declare function runFeedbackLoopGreedy(compile: CompileMetrics, opts?: GreedyOptions): GreedyResult;
+export declare function formatAdjustments(adjustments: readonly TuneAdjustment[]): string;

package/dist/vascend/context-autotuner.js

@@ -0,0 +1,231 @@
+// Context Autotuner (metodo Danilov, Memory OS) -- L2: l'anello di retroazione.
+//
+// Il salto sopra le metriche: non basta MISURARE il contesto compilato, bisogna
+// USARE la misura per RICONFIGURARE lo scorer. Questo modulo chiude l'anello.
+//
+//   compile -> ContextMetrics -> autotune(weights, thresholds) -> compile ...
+//
+// E' il cuore dell'AUTO-MIGLIORAMENTO dell'architettura del context: a parita'
+// di store, il sistema regola da solo i pesi multi-fattore e le soglie di tier
+// finche' le metriche non convergono verso target di qualita'.
+//
+// Diagnosi -> aggiustamento (tutto deterministico, niente provider, niente rete):
+//   - stale_memory_rate alto      -> alza conflictRisk (caccia gli obsoleti)
+//   - context_utility basso       -> alza relevance, abbassa tokenCost
+//   - evidence_coverage basso     -> abbassa la soglia HIGH (piu' corpo)
+//   - evidence_coverage troppo alto + utility basso -> alza la soglia HIGH
+//   - decision_consistency falso  -> alza conflictRisk (decisioni superseded fuori)
+//
+// Modulo PURO e DETERMINISTICO: stessi input -> stesso output. Ogni passo e'
+// limitato da uno step massimo e i pesi sono clampati in un range sano, cosi'
+// l'anello e' STABILE (non diverge) e MONOTONO verso i target.
+import { DEFAULT_WEIGHTS, DEFAULT_THRESHOLDS } from "./context-scorer.js";
+export const DEFAULT_TARGETS = {
+    minUtility: 8,
+    maxStaleRate: 0.1,
+    minEvidenceCoverage: 0.35,
+    maxEvidenceCoverage: 0.75,
+};
+export const DEFAULT_CONFIG = {
+    weights: DEFAULT_WEIGHTS,
+    thresholds: DEFAULT_THRESHOLDS,
+};
+// --- range sani di clamping -------------------------------------------------
+// Un controllore senza limiti diverge. Ogni leva ha un intervallo entro cui
+// puo' muoversi: cosi' l'anello resta stabile a prescindere dalle metriche.
+// Esportati: l'esploratore multi-pattern (context-pattern-explorer) li riusa per
+// generare e sanificare i suoi pattern dentro lo stesso spazio sano.
+export const WEIGHT_BOUNDS = {
+    relevance: [0.5, 2.0],
+    dependency: [0.3, 1.5],
+    trust: [0.2, 1.2],
+    freshness: [0.1, 1.0],
+    novelty: [0.1, 1.0],
+    conflictRisk: [0.5, 2.5],
+    tokenCost: [0.05, 0.8],
+};
+export const HIGH_BOUNDS = [0.6, 1.8];
+export const MID_BOUNDS = [0.2, 0.9];
+// Passo massimo per iterazione: piccolo = anello dolce e stabile.
+const STEP = 0.1;
+const THRESH_STEP = 0.08;
+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;
+}
+// Diagnostica le metriche rispetto ai target e produce la lista di correzioni.
+// PURA: nessun side-effect. Ogni correzione e' limitata a +/- STEP.
+export function diagnose(metrics, targets = DEFAULT_TARGETS) {
+    const adj = [];
+    // 1) Troppi obsoleti fra gli inclusi -> penalizza di piu' il conflitto.
+    if (metrics.staleMemoryRate > targets.maxStaleRate) {
+        const severity = Math.min(1, (metrics.staleMemoryRate - targets.maxStaleRate) / Math.max(0.01, 1 - targets.maxStaleRate));
+        adj.push({
+            lever: "conflictRisk",
+            delta: +round3(STEP * (0.5 + severity)),
+            reason: `stale_memory_rate ${metrics.staleMemoryRate} > ${targets.maxStaleRate}`,
+        });
+    }
+    // 2) Decisioni superseded entrate -> rinforza il conflictRisk con decisione.
+    if (!metrics.decisionConsistency) {
+        adj.push({
+            lever: "conflictRisk",
+            delta: +round3(STEP),
+            reason: "decision_consistency=false: decisione obsoleta inclusa",
+        });
+    }
+    // 3) Densita' utile bassa -> piu' rilevanza, meno penalita' di costo.
+    if (metrics.contextUtility < targets.minUtility) {
+        adj.push({
+            lever: "relevance",
+            delta: +round3(STEP),
+            reason: `context_utility ${metrics.contextUtility} < ${targets.minUtility}`,
+        });
+        adj.push({
+            lever: "tokenCost",
+            delta: -round3(STEP * 0.5),
+            reason: `context_utility basso: riduci penalita' di costo`,
+        });
+    }
+    // 4) Copertura di evidenza (corpo) troppo bassa -> abbassa la soglia HIGH
+    //    cosi' piu' candidati entrano come corpo invece che come handle.
+    if (metrics.evidenceCoverage < targets.minEvidenceCoverage) {
+        adj.push({
+            lever: "thresholdHigh",
+            delta: -round3(THRESH_STEP),
+            reason: `evidence_coverage ${metrics.evidenceCoverage} < ${targets.minEvidenceCoverage}`,
+        });
+    }
+    else if (metrics.evidenceCoverage > targets.maxEvidenceCoverage && metrics.contextUtility < targets.minUtility) {
+        // 5) Quasi tutto e' corpo ma la densita' resta bassa -> alza la soglia HIGH
+        //    (troppo corpo gonfia i token senza aggiungere utilita').
+        adj.push({
+            lever: "thresholdHigh",
+            delta: +round3(THRESH_STEP),
+            reason: `evidence_coverage ${metrics.evidenceCoverage} > ${targets.maxEvidenceCoverage} con utility bassa`,
+        });
+    }
+    return adj;
+}
+// --- applicazione: config + aggiustamenti -> nuova config -------------------
+// Applica le correzioni a una configurazione, sommando i delta per leva e
+// clampando ogni leva nel suo range sano. PURA e deterministica.
+export function applyAdjustments(config, adjustments) {
+    // Somma i delta per leva (piu' correzioni possono toccare la stessa leva).
+    const weightDelta = {};
+    let highDelta = 0;
+    let midDelta = 0;
+    for (const a of adjustments) {
+        if (a.lever === "thresholdHigh")
+            highDelta += a.delta;
+        else if (a.lever === "thresholdMid")
+            midDelta += a.delta;
+        else
+            weightDelta[a.lever] = (weightDelta[a.lever] ?? 0) + a.delta;
+    }
+    const weights = {
+        relevance: tuneWeight("relevance", config.weights.relevance, weightDelta.relevance),
+        dependency: tuneWeight("dependency", config.weights.dependency, weightDelta.dependency),
+        trust: tuneWeight("trust", config.weights.trust, weightDelta.trust),
+        freshness: tuneWeight("freshness", config.weights.freshness, weightDelta.freshness),
+        novelty: tuneWeight("novelty", config.weights.novelty, weightDelta.novelty),
+        conflictRisk: tuneWeight("conflictRisk", config.weights.conflictRisk, weightDelta.conflictRisk),
+        tokenCost: tuneWeight("tokenCost", config.weights.tokenCost, weightDelta.tokenCost),
+    };
+    // La soglia MID resta sempre sotto la HIGH (invariante di tier).
+    const high = clamp(round3(config.thresholds.high + highDelta), HIGH_BOUNDS[0], HIGH_BOUNDS[1]);
+    const midRaw = clamp(round3(config.thresholds.mid + midDelta), MID_BOUNDS[0], MID_BOUNDS[1]);
+    const mid = Math.min(midRaw, round3(high - 0.1));
+    return { weights, thresholds: { high, mid } };
+}
+function tuneWeight(lever, current, delta) {
+    const [lo, hi] = WEIGHT_BOUNDS[lever];
+    return clamp(round3(current + (delta ?? 0)), lo, hi);
+}
+// Un solo passo dell'anello: diagnosi + applicazione. Ritorna la nuova config e
+// le correzioni applicate (per traccia/log).
+export function autotuneStep(config, metrics, targets = DEFAULT_TARGETS) {
+    const adjustments = diagnose(metrics, targets);
+    return { config: applyAdjustments(config, adjustments), adjustments };
+}
+// --- punteggio scalare di qualita' (per misurare il progresso) --------------
+// Riduce le metriche a un singolo numero 0..100: la "bonta'" del contesto.
+// Serve all'anello per dire se un passo MIGLIORA davvero (monotonia) e per
+// decidere la convergenza. Pesa densita' utile, freschezza dalla memoria e
+// copertura di evidenza dentro la banda target; penalizza stale e incoerenza.
+export function qualityScore(metrics, targets = DEFAULT_TARGETS) {
+    // Densita' utile normalizzata sul target (cap a 1).
+    const utility = clamp(metrics.contextUtility / Math.max(1, targets.minUtility), 0, 1);
+    // Stale: 1 quando rate=0, scende a 0 quando supera abbondantemente il max.
+    const staleSlack = Math.max(0.01, targets.maxStaleRate * 3);
+    const cleanliness = clamp(1 - metrics.staleMemoryRate / staleSlack, 0, 1);
+    // Copertura dentro la banda [min,max] = 1; fuori banda scende linearmente.
+    const cov = metrics.evidenceCoverage;
+    let coverage;
+    if (cov >= targets.minEvidenceCoverage && cov <= targets.maxEvidenceCoverage) {
+        coverage = 1;
+    }
+    else if (cov < targets.minEvidenceCoverage) {
+        coverage = clamp(cov / Math.max(0.01, targets.minEvidenceCoverage), 0, 1);
+    }
+    else {
+        coverage = clamp(1 - (cov - targets.maxEvidenceCoverage) / Math.max(0.01, 1 - targets.maxEvidenceCoverage), 0, 1);
+    }
+    const consistency = metrics.decisionConsistency ? 1 : 0;
+    // Combinazione pesata -> 0..100. Pulizia e densita' pesano di piu'.
+    const raw = 0.32 * utility + 0.28 * cleanliness + 0.22 * coverage + 0.18 * consistency;
+    return Math.round(raw * 100);
+}
+// Convergenza: nessuna correzione proposta E qualita' sopra una soglia, oppure
+// il punteggio non migliora piu' in modo apprezzabile.
+export function hasConverged(adjustments, scoreDelta, minDelta = 1) {
+    return adjustments.length === 0 || scoreDelta < minDelta;
+}
+// L'autotuner SINGLE-PATH puro e autocontenuto: parte da una config, applica la
+// diagnosi greedy e converge al primo ottimo locale. Identico nello spirito a
+// runFeedbackLoop (context-feedback-loop) ma senza dipendenze sul compiler reale,
+// cosi' l'esploratore multi-pattern puo' derivare i suoi punti greedy/restart
+// senza creare un ciclo di import. MONOTONO: tiene sempre la config migliore.
+export function runFeedbackLoopGreedy(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;
+    let metrics = compile(config);
+    let score = qualityScore(metrics, targets);
+    const initialScore = score;
+    let bestConfig = config;
+    let bestScore = score;
+    let rounds = 0;
+    for (let round = 0; round < maxRounds; round++) {
+        rounds++;
+        const step = autotuneStep(config, metrics, targets);
+        if (step.adjustments.length === 0)
+            break;
+        const nextMetrics = compile(step.config);
+        const nextScore = qualityScore(nextMetrics, targets);
+        const gain = nextScore - score;
+        if (nextScore > bestScore) {
+            bestScore = nextScore;
+            bestConfig = step.config;
+        }
+        if (hasConverged(step.adjustments, gain, minGain))
+            break;
+        config = step.config;
+        metrics = nextMetrics;
+        score = nextScore;
+    }
+    return { bestConfig, bestScore, initialScore, rounds };
+}
+// Formatta un passo dell'anello come blocco Danilov (log/TUI).
+export function formatAdjustments(adjustments) {
+    if (!adjustments.length)
+        return "@autotune: nessuna correzione (convergenza locale)";
+    return adjustments
+        .map((a) => `@tune[${a.lever}]: ${a.delta > 0 ? "+" : ""}${a.delta}  [ ${a.reason} ]`)
+        .join("\n");
+}

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

@@ -0,0 +1,45 @@
+import type { MemoryDomain, MemoryEvent } from "./memory-store.js";
+export type ContextKind = "room" | "decision" | "note" | "asset" | "kingdom" | "task" | "event" | "file";
+export type ContextStatus = "active" | "superseded" | "archived";
+export type ContextConfidence = "low" | "medium" | "high";
+export interface ContextCandidate {
+    readonly id: string;
+    readonly kind: ContextKind;
+    readonly domain: MemoryDomain;
+    readonly subject: string;
+    readonly summary: string;
+    readonly body: string;
+    readonly terms: readonly string[];
+    readonly links: readonly string[];
+    readonly createdAt: number;
+    readonly trust: ContextConfidence;
+    readonly status: ContextStatus;
+    readonly supersededBy: string | null;
+    readonly dependency: boolean;
+    readonly scopeId: string | null;
+}
+export type ContextCandidateInput = Partial<ContextCandidate> & Pick<ContextCandidate, "id" | "kind">;
+export interface ContextScoreFactors {
+    readonly relevance: number;
+    readonly dependency: number;
+    readonly trust: number;
+    readonly freshness: number;
+    readonly novelty: number;
+    readonly conflictRisk: number;
+    readonly tokenCost: number;
+}
+export type ContextTier = "high" | "mid" | "low";
+export interface ContextScore {
+    readonly candidate: ContextCandidate;
+    readonly score: number;
+    readonly factors: ContextScoreFactors;
+    readonly tier: ContextTier;
+}
+export declare function normalizeCandidate(input: ContextCandidateInput): ContextCandidate;
+export declare function kindFromEvent(event: Pick<MemoryEvent, "domain" | "type">): ContextKind;
+export declare function candidateFromEvent(event: MemoryEvent, opts?: {
+    readonly scopeId?: string;
+    readonly dependency?: boolean;
+}): ContextCandidate;
+export declare function estimateCandidateTokens(candidate: ContextCandidate, form: "body" | "handle"): number;
+export declare function confidenceWeight(confidence: ContextConfidence): number;

package/dist/vascend/context-candidate.js

@@ -0,0 +1,150 @@
+// Tipi del dominio CANDIDATO di contesto (metodo Danilov, Memory OS).
+//
+// Un ContextCandidate e' qualunque frammento di memoria che POTREBBE entrare
+// nella context window del turno corrente: una stanza, una decisione, una nota,
+// un file/asset, un messaggio kingdom, un task o un evento. Il Context Window
+// Compiler non manda "piu' memoria": sceglie QUALE candidato merita token,
+// in quale forma e in quale posizione.
+//
+// Modulo PURO: solo tipi e helper deterministici, nessun side-effect, nessuna
+// dipendenza a runtime. Combacia per struttura con MemoryEvent (memory-store)
+// senza dipenderne in modo rigido: un evento si converte in candidato tramite
+// candidateFromEvent.
+// --- helper deterministici --------------------------------------------------
+// Normalizza una forma tollerante in un ContextCandidate completo, applicando
+// default sicuri. Deterministico.
+export function normalizeCandidate(input) {
+    return {
+        id: input.id,
+        kind: input.kind,
+        domain: input.domain ?? "system",
+        subject: (input.subject ?? "").trim(),
+        summary: (input.summary ?? "").trim(),
+        body: (input.body ?? "").trim(),
+        terms: dedupeTerms(input.terms ?? []),
+        links: dedupeValues(input.links ?? []),
+        createdAt: typeof input.createdAt === "number" ? input.createdAt : 0,
+        trust: input.trust ?? "medium",
+        status: input.status ?? "active",
+        supersededBy: input.supersededBy ?? null,
+        dependency: input.dependency ?? false,
+        scopeId: input.scopeId ?? null,
+    };
+}
+// Mappa il tipo evento del Memory OS al ContextKind piu' adatto.
+export function kindFromEvent(event) {
+    switch (event.domain) {
+        case "decisions":
+            return "decision";
+        case "notes":
+            return "note";
+        case "assets":
+            return "asset";
+        case "kingdom":
+            return "kingdom";
+        case "plan":
+            return "task";
+        case "rooms":
+            return "room";
+        case "files":
+            return "file";
+        case "code":
+            // Convenzione concordata col Dev Context Layout: gli eventi del code graph
+            // hanno kind "file" cosi' atterrano nella zona "code graph caldo".
+            return "file";
+        default:
+            return "event";
+    }
+}
+// Confidenza implicita per dominio: decisioni ed eventi di sistema/plan sono
+// canonici (high); note/asset utente sono medium; kingdom/file sono low di
+// default (rumorosi finche' non promossi).
+function trustForDomain(domain) {
+    if (domain === "decisions" || domain === "plan" || domain === "system")
+        return "high";
+    if (domain === "kingdom" || domain === "files")
+        return "low";
+    return "medium";
+}
+// Estrae status/supersededBy dal payload dell'evento (campi opzionali del grafo
+// di supersessione), con default "active".
+function supersessionFromEvent(event) {
+    const payload = event.payload ?? {};
+    const rawStatus = typeof payload["status"] === "string" ? payload["status"] : "active";
+    const status = rawStatus === "superseded" || rawStatus === "archived" ? rawStatus : "active";
+    const supersededBy = typeof payload["supersededBy"] === "string" ? payload["supersededBy"] : null;
+    return { status, supersededBy };
+}
+// Converte un MemoryEvent in ContextCandidate. Deterministico: nessuna lettura
+// esterna, solo mappatura dei campi. `dependency` e' un override esplicito.
+export function candidateFromEvent(event, opts = {}) {
+    const { status, supersededBy } = supersessionFromEvent(event);
+    const confidence = typeof event.payload?.["confidence"] === "string"
+        ? event.payload["confidence"]
+        : trustForDomain(event.domain);
+    return normalizeCandidate({
+        id: event.id,
+        kind: kindFromEvent(event),
+        domain: event.domain,
+        subject: event.subject,
+        summary: event.summary,
+        body: event.body,
+        terms: event.terms,
+        links: event.links.map((link) => link.target),
+        createdAt: event.createdAt,
+        trust: confidence,
+        status,
+        supersededBy,
+        // Un test rotto o un contratto/API appena cambiato e' un prerequisito
+        // operativo, non semplice cronaca. L'override esplicito del chiamante resta
+        // autoritativo per i casi che vogliono degradarlo.
+        dependency: opts.dependency ?? isHotCodeDependency(event),
+        ...(opts.scopeId ? { scopeId: opts.scopeId } : {}),
+    });
+}
+function isHotCodeDependency(event) {
+    return event.domain === "code" && (event.type === "code.test.failed" ||
+        event.type === "code.contract.changed" ||
+        event.type === "code.api.changed");
+}
+// Stima deterministica dei token di un candidato nella forma indicata.
+// Approssimazione classica: ~4 caratteri per token. La forma "body" usa il
+// corpo completo; "handle" usa solo id+subject+summary.
+export function estimateCandidateTokens(candidate, form) {
+    const text = form === "body"
+        ? `${candidate.id} ${candidate.subject} ${candidate.summary} ${candidate.body}`
+        : `${candidate.id} ${candidate.subject} ${candidate.summary}`;
+    return Math.max(1, Math.ceil(text.length / 4));
+}
+// Numero di confidenza in [0,1] per i tre livelli.
+export function confidenceWeight(confidence) {
+    if (confidence === "high")
+        return 1;
+    if (confidence === "medium")
+        return 0.6;
+    return 0.3;
+}
+function dedupeTerms(terms) {
+    const seen = new Set();
+    const out = [];
+    for (const raw of terms) {
+        const t = raw.trim().toLowerCase();
+        if (!t || seen.has(t))
+            continue;
+        seen.add(t);
+        out.push(t);
+    }
+    return out;
+}
+function dedupeValues(values) {
+    const seen = new Set();
+    const out = [];
+    for (const raw of values) {
+        const value = raw.trim();
+        if (!value || seen.has(value))
+            continue;
+        seen.add(value);
+        out.push(value);
+    }
+    return out;
+}

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

@@ -0,0 +1,51 @@
+import { type ContextCandidate, type ContextConfidence, type ContextKind, type ContextStatus } from "./context-candidate.js";
+import type { MemoryDomain } from "./memory-store.js";
+export type ExpansionLevel = 0 | 1 | 2 | 3 | 4;
+export declare const EXPANSION_LEVELS: readonly ExpansionLevel[];
+export declare const EXPANSION_LABEL: Readonly<Record<ExpansionLevel, string>>;
+export interface CapsuleHeader {
+    readonly id: string;
+    readonly domain: MemoryDomain;
+    readonly type: ContextKind;
+    readonly status: ContextStatus;
+    readonly confidence: ContextConfidence;
+}
+export interface CapsuleMetrics {
+    readonly tokenCost: number;
+    readonly utility: number;
+    readonly freshness: number;
+}
+export interface CapsuleRecall {
+    readonly domains: readonly MemoryDomain[];
+    readonly query?: string;
+    readonly id?: string;
+}
+export interface CapsuleLineage {
+    readonly supersedes?: readonly string[];
+    readonly supersededBy?: string | null;
+    readonly derivedFrom?: readonly string[];
+    readonly createdAt: number;
+}
+export interface ContextCapsule {
+    readonly header: CapsuleHeader;
+    readonly summary: string;
+    readonly reason: string;
+    readonly proof: string;
+    readonly body: string;
+    readonly terms: readonly string[];
+    readonly recall: CapsuleRecall;
+    readonly metrics: CapsuleMetrics;
+    readonly lineage: CapsuleLineage;
+    readonly expansionLevel: ExpansionLevel;
+}
+export interface CapsuleFromCandidateOptions {
+    readonly now?: number;
+    readonly utility?: number;
+    readonly recallQuery?: string;
+    readonly expansionLevel?: ExpansionLevel;
+}
+export declare function capsuleFromCandidate(c: ContextCandidate, opts?: CapsuleFromCandidateOptions): ContextCapsule;
+export declare function capsulesFromCandidates(candidates: readonly ContextCandidate[], opts?: CapsuleFromCandidateOptions): readonly ContextCapsule[];
+export declare function withExpansion(capsule: ContextCapsule, level: ExpansionLevel): ContextCapsule;
+export declare function confidenceWeightOf(confidence: ContextConfidence): number;
+export declare function isStale(capsule: ContextCapsule): boolean;