@vascend/talos 0.1.0

package/dist/vascend/context-retriever.js

@@ -0,0 +1,243 @@
+import { ContextSearchIndex } from "./context-search-index.js";
+import { activeCandidates } from "./supersession-graph.js";
+import { buildSynonyms, expandQuery, bm25Score, tokenize, } from "./lexical-search.js";
+const MAX_GRAPH_HOPS = 2;
+const MAX_GRAPH_SEEDS = 8;
+const MAX_GRAPH_NEIGHBORS = 12;
+const MAX_GRAPH_VISITS = 96;
+const SECOND_HOP_DECAY = 0.72;
+const MIN_TRANSITIVE_WEIGHT = 0.5;
+const RRF_K = 60;
+const DEFAULT_SYNONYM_INDEX = buildSynonyms();
+const GRAPH_RRF_WEIGHT = 1.15;
+// Esegue il retrieval ibrido. Deterministico.
+export function retrieve(pool, opts) {
+    const limit = opts.limit && opts.limit > 0 ? opts.limit : 24;
+    const minScore = typeof opts.minScore === "number" ? opts.minScore : 0;
+    const expandLinks = opts.expandLinks ?? true;
+    const synonyms = opts.synonyms ?? DEFAULT_SYNONYM_INDEX;
+    const index = opts.legacy ? undefined : opts.index ?? new ContextSearchIndex(pool, undefined, opts.dropSuperseded ?? true);
+    const candidates = index?.candidates ?? ((opts.dropSuperseded ?? true) ? activeCandidates(pool) : pool);
+    if (!candidates.length)
+        return [];
+    // --- 1) ranking lessicale BM25 ---
+    const docs = index?.docs ?? candidates.map((c) => ({
+        ref: c,
+        tokens: tokenize(`${c.terms.join(" ")} ${c.subject} ${c.summary} ${c.body}`),
+    }));
+    const queryTokens = tokenize(opts.query);
+    const queryTerms = expandQuery(queryTokens, synonyms);
+    const scored = index?.lexical.score(queryTerms) ?? bm25Score(docs, queryTerms);
+    const scoreById = new Map();
+    for (const s of scored)
+        scoreById.set(s.ref.id, s.score);
+    // Match diretti sopra soglia, ordinati per score. Non tronchiamo ancora al
+    // limite: i vicini strutturali devono poter competere con i match lessicali
+    // deboli anche quando questi ultimi saturano il pool.
+    const direct = scored
+        .filter((s) => s.score > minScore)
+        .sort((a, b) => b.score - a.score || a.ref.id.localeCompare(b.ref.id));
+    if (!direct.length)
+        return [];
+    // Fallback lessicale puro: preserva score e ordinamento BM25 quando il
+    // chiamante disattiva il grafo o la traversata non scopre alcun vicino.
+    if (!expandLinks)
+        return lexicalFallback(direct, limit);
+    // --- 2) link graph bounded: massimo due hop dai top match ---
+    const graph = expandGraph(candidates, direct, scoreById, limit, index?.links);
+    if (!graph.length)
+        return lexicalFallback(direct, limit);
+    // --- 3) Reciprocal Rank Fusion ---
+    // BM25, propagazione e numero di archi hanno scale differenti. Fondiamo i
+    // RANK, modulando soltanto il canale grafo per la forza relativa del path.
+    // I match che contengono tutti i token originali della query restano sempre
+    // davanti ai candidati graph-only; tra loro mantengono l'ordine BM25.
+    const lexicalRanks = rankMap(direct.map((item) => item.ref.id));
+    const graphRanks = rankMap(graph.map((item) => item.candidate.id));
+    const graphById = new Map(graph.map((item) => [item.candidate.id, item]));
+    const maxGraph = graph[0]?.score ?? 1;
+    const exactIds = new Set(docs
+        .filter((doc) => isExactMatch(queryTokens, doc.tokens) && lexicalRanks.has(doc.ref.id))
+        .map((doc) => doc.ref.id));
+    const byId = new Map(candidates.map((candidate) => [candidate.id, candidate]));
+    const union = new Set([...lexicalRanks.keys(), ...graphRanks.keys()]);
+    const fused = [];
+    for (const id of union) {
+        const candidate = byId.get(id);
+        if (!candidate)
+            continue;
+        const lexRank = lexicalRanks.get(id);
+        const graphRank = graphRanks.get(id);
+        const graphHit = graphById.get(id);
+        const lexScore = scoreById.get(id) ?? 0;
+        const graphScore = graphHit?.score ?? 0;
+        const lexContribution = lexRank === undefined ? 0 : 1 / (RRF_K + lexRank);
+        const graphStrength = maxGraph > 0 ? graphScore / maxGraph : 0;
+        const graphContribution = graphRank === undefined
+            ? 0
+            : (GRAPH_RRF_WEIGHT * graphStrength) / (RRF_K + graphRank);
+        fused.push({
+            candidate,
+            lexScore,
+            graphScore,
+            retrievalScore: lexContribution + graphContribution,
+            viaLink: lexRank === undefined,
+        });
+    }
+    return [...protectExactScores(fused, exactIds, lexicalRanks)]
+        .sort((a, b) => compareFused(a, b, exactIds, lexicalRanks))
+        .slice(0, limit);
+}
+function lexicalFallback(direct, limit) {
+    return direct.slice(0, limit).map((item) => ({
+        candidate: item.ref,
+        lexScore: item.score,
+        graphScore: 0,
+        retrievalScore: item.score,
+        viaLink: false,
+    }));
+}
+function expandGraph(candidates, direct, scoreById, limit, links) {
+    const seedLimit = Math.min(direct.length, MAX_GRAPH_SEEDS, Math.max(2, Math.ceil(limit / 2)));
+    const neighborLimit = Math.min(MAX_GRAPH_NEIGHBORS, Math.max(4, limit));
+    const visitLimit = Math.min(MAX_GRAPH_VISITS, Math.max(16, limit * 4));
+    const neighborsCache = new Map();
+    const hits = new Map();
+    let visits = 0;
+    const neighborsOf = (source) => {
+        const cached = neighborsCache.get(source.id);
+        if (cached)
+            return cached;
+        const neighbors = (links ? [...links.neighbors(source.id)] : candidates
+            .filter((candidate) => candidate.id !== source.id)
+            .map((candidate) => ({ candidate, weight: relationWeight(source, candidate) }))
+            .filter((edge) => edge.weight > 0))
+            .sort((a, b) => b.weight - a.weight ||
+            (scoreById.get(b.candidate.id) ?? 0) - (scoreById.get(a.candidate.id) ?? 0) ||
+            a.candidate.id.localeCompare(b.candidate.id));
+        neighborsCache.set(source.id, neighbors);
+        return neighbors;
+    };
+    for (const seed of direct.slice(0, seedLimit)) {
+        const seen = new Map([[seed.ref.id, seed.score]]);
+        const queue = [
+            { candidate: seed.ref, score: seed.score, hop: 0 },
+        ];
+        while (queue.length && visits < visitLimit) {
+            const current = queue.shift();
+            if (!current)
+                break;
+            const allNeighbors = neighborsOf(current.candidate);
+            const degreePenalty = allNeighbors.length > neighborLimit
+                ? Math.sqrt(neighborLimit / allNeighbors.length)
+                : 1;
+            for (const edge of allNeighbors.slice(0, neighborLimit)) {
+                const nextHop = current.hop + 1;
+                if (nextHop > MAX_GRAPH_HOPS)
+                    continue;
+                // La parentela di namespace e altri archi deboli sono utili come
+                // tie-break a un hop, ma non possono diventare ponti transitivi.
+                if (nextHop === 2 && edge.weight < MIN_TRANSITIVE_WEIGHT)
+                    continue;
+                const decay = nextHop === 2 ? SECOND_HOP_DECAY : 1;
+                const propagated = current.score * edge.weight * degreePenalty * decay;
+                if (propagated <= 0 || propagated <= (seen.get(edge.candidate.id) ?? 0))
+                    continue;
+                seen.set(edge.candidate.id, propagated);
+                if (edge.candidate.id === seed.ref.id)
+                    continue;
+                const previous = hits.get(edge.candidate.id);
+                if (!previous || propagated > previous.score) {
+                    hits.set(edge.candidate.id, { candidate: edge.candidate, score: propagated, hop: nextHop });
+                }
+                visits += 1;
+                if (visits >= visitLimit)
+                    break;
+                if (nextHop < MAX_GRAPH_HOPS && edge.weight >= MIN_TRANSITIVE_WEIGHT) {
+                    queue.push({ candidate: edge.candidate, score: propagated, hop: 1 });
+                }
+            }
+        }
+    }
+    return [...hits.values()].sort((a, b) => b.score - a.score || a.hop - b.hop || a.candidate.id.localeCompare(b.candidate.id));
+}
+function rankMap(ids) {
+    return new Map(ids.map((id, index) => [id, index + 1]));
+}
+function isExactMatch(queryTokens, documentTokens) {
+    const query = [...new Set(queryTokens)];
+    if (!query.length)
+        return false;
+    const document = new Set(documentTokens);
+    return query.every((token) => document.has(token));
+}
+// La sola precedenza nel sort non basta: il Context Window Compiler normalizza
+// retrievalScore e riesegue uno scoring multi-fattore. Gli exact occupano
+// quindi una fascia numerica sopra ogni altro candidato, ordinata secondo BM25.
+function protectExactScores(items, exactIds, lexicalRanks) {
+    const exact = items
+        .filter((item) => exactIds.has(item.candidate.id))
+        .sort((a, b) => (lexicalRanks.get(a.candidate.id) ?? Infinity) - (lexicalRanks.get(b.candidate.id) ?? Infinity)
+        || a.candidate.id.localeCompare(b.candidate.id));
+    if (!exact.length)
+        return items;
+    const ceiling = items.reduce((max, item) => Math.max(max, item.retrievalScore), 0);
+    const step = Math.max(1e-9, ceiling * 0.01);
+    const protectedScore = new Map(exact.map((item, index) => [item.candidate.id, ceiling + step * (exact.length - index)]));
+    return items.map((item) => {
+        const retrievalScore = protectedScore.get(item.candidate.id);
+        return retrievalScore === undefined ? item : { ...item, retrievalScore };
+    });
+}
+function compareFused(a, b, exactIds, lexicalRanks) {
+    const aExact = exactIds.has(a.candidate.id);
+    const bExact = exactIds.has(b.candidate.id);
+    if (aExact !== bExact)
+        return aExact ? -1 : 1;
+    if (aExact && bExact) {
+        return (lexicalRanks.get(a.candidate.id) ?? Infinity) - (lexicalRanks.get(b.candidate.id) ?? Infinity)
+            || a.candidate.id.localeCompare(b.candidate.id);
+    }
+    return b.retrievalScore - a.retrievalScore
+        || Number(a.viaLink) - Number(b.viaLink)
+        || b.lexScore - a.lexScore
+        || a.candidate.id.localeCompare(b.candidate.id);
+}
+// Peso della relazione strutturale. I link tipizzati sono il segnale piu'
+// forte; una citazione testuale dell'id e' meno affidabile; la semplice
+// appartenenza allo stesso castello serve solo come tie-break contestuale.
+function relationWeight(seed, candidate) {
+    if (seed.links.includes(candidate.id) || candidate.links.includes(seed.id))
+        return 0.68;
+    if (mentions(seed, candidate.id) || mentions(candidate, seed.id))
+        return 0.52;
+    if (sameCastle(seed.id, candidate.id))
+        return 0.18;
+    return 0;
+}
+// Vero se il testo del candidato cita l'id target (riferimento esplicito).
+function mentions(c, targetId) {
+    if (!targetId)
+        return false;
+    const hay = `${c.summary} ${c.body} ${c.terms.join(" ")}`.toLowerCase();
+    const needle = targetId.toLowerCase();
+    let from = 0;
+    while (from < hay.length) {
+        const index = hay.indexOf(needle, from);
+        if (index < 0)
+            return false;
+        const before = index > 0 ? hay[index - 1] ?? "" : "";
+        const afterIndex = index + needle.length;
+        const after = afterIndex < hay.length ? hay[afterIndex] ?? "" : "";
+        if (!/[a-z0-9_]/i.test(before) && !/[a-z0-9_]/i.test(after))
+            return true;
+        from = index + needle.length;
+    }
+    return false;
+}
+// Vero se due id appartengono allo stesso castello (prefisso prima di "/").
+function sameCastle(a, b) {
+    const pa = a.includes("/") ? a.slice(0, a.indexOf("/")) : "";
+    const pb = b.includes("/") ? b.slice(0, b.indexOf("/")) : "";
+    return Boolean(pa) && pa === pb;
+}

package/dist/vascend/context-scope-index.d.ts

@@ -0,0 +1,5 @@
+/** Frame content affects retrieval only through project membership, not diagnostics. */
+export declare function projectMemoryScopes(sessionDir: string, projectKey: string): readonly string[];
+/** Synchronous notification closes the gap before filesystem watcher delivery. */
+export declare function contextFrameWritten(sessionDir: string, path: string): void;
+export declare function clearContextScopeIndexes(): void;

package/dist/vascend/context-scope-index.js

@@ -0,0 +1,96 @@
+import { readdirSync, readFileSync, statSync, watch } from "node:fs";
+import { join, resolve } from "node:path";
+const catalogs = new Map();
+const RECONCILE_MS = 30_000;
+function stamp(path) {
+    try {
+        const stat = statSync(path);
+        return stat.size + ":" + stat.mtimeMs + ":" + stat.ctimeMs;
+    }
+    catch {
+        return "";
+    }
+}
+/** Frame content affects retrieval only through project membership, not diagnostics. */
+export function projectMemoryScopes(sessionDir, projectKey) {
+    const dir = resolve(sessionDir, "context-fabric");
+    let catalog = catalogs.get(dir);
+    if (!catalog) {
+        catalog = { frames: new Map(), dirty: new Set(), directoryStamp: "", reconciledAt: 0 };
+        catalogs.set(dir, catalog);
+        if (catalogs.size > 32) {
+            const oldest = catalogs.keys().next().value;
+            catalogs.get(oldest)?.watcher?.close();
+            catalogs.delete(oldest);
+        }
+    }
+    const directoryStamp = stamp(dir);
+    const reconcile = Date.now() - catalog.reconciledAt >= RECONCILE_MS;
+    if (reconcile || directoryStamp !== catalog.directoryStamp) {
+        let files = [];
+        try {
+            files = readdirSync(dir).filter((name) => name.endsWith(".json"));
+        }
+        catch { /* no catalog yet */ }
+        const names = new Set(files);
+        for (const name of catalog.frames.keys())
+            if (!names.has(name))
+                catalog.frames.delete(name);
+        for (const name of files) {
+            if (!catalog.frames.has(name) || reconcile && catalog.frames.get(name).stamp !== stamp(join(dir, name)))
+                catalog.dirty.add(name);
+        }
+        catalog.directoryStamp = directoryStamp;
+        catalog.reconciledAt = Date.now();
+        if (!catalog.watcher && directoryStamp) {
+            try {
+                const target = catalog;
+                catalog.watcher = watch(dir, { persistent: false }, (_event, name) => {
+                    if (name?.toString().endsWith(".json"))
+                        target.dirty.add(name.toString());
+                });
+                catalog.watcher.on("error", () => { target.watcher?.close(); target.watcher = undefined; target.reconciledAt = 0; });
+            }
+            catch { /* periodic reconciliation remains authoritative */ }
+        }
+    }
+    for (const name of catalog.dirty)
+        readFrame(catalog, dir, name);
+    catalog.dirty.clear();
+    const scopes = new Map();
+    for (const frame of catalog.frames.values())
+        if (frame.projectKey === projectKey) {
+            scopes.set(frame.scope, Math.max(scopes.get(frame.scope) ?? 0, frame.updatedAt));
+        }
+    return [...scopes].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([scope]) => scope);
+}
+/** Synchronous notification closes the gap before filesystem watcher delivery. */
+export function contextFrameWritten(sessionDir, path) {
+    const dir = resolve(sessionDir, "context-fabric");
+    const catalog = catalogs.get(dir);
+    if (!catalog)
+        return;
+    const name = path.replaceAll("\\", "/").split("/").pop();
+    readFrame(catalog, dir, name);
+    catalog.dirty.delete(name);
+}
+function readFrame(catalog, dir, name) {
+    try {
+        const path = join(dir, name);
+        const frame = JSON.parse(readFileSync(path, "utf8"));
+        const scope = frame.receipt?.memoryScopeId;
+        if (typeof frame.projectKey !== "string" || typeof scope !== "string" || !scope) {
+            catalog.frames.delete(name);
+            return;
+        }
+        catalog.frames.set(name, { projectKey: frame.projectKey, scope, updatedAt: Number(frame.updatedAt) || 0, stamp: stamp(path) });
+    }
+    catch {
+        catalog.frames.delete(name);
+    }
+}
+export function clearContextScopeIndexes() {
+    for (const catalog of catalogs.values())
+        catalog.watcher?.close();
+    catalogs.clear();
+}

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

@@ -0,0 +1,35 @@
+import { type ContextCandidate, type ContextScore, type ContextScoreFactors, type ContextTier } from "./context-candidate.js";
+export interface ScoreWeights {
+    readonly relevance: number;
+    readonly dependency: number;
+    readonly trust: number;
+    readonly freshness: number;
+    readonly novelty: number;
+    readonly conflictRisk: number;
+    readonly tokenCost: number;
+}
+export declare const DEFAULT_WEIGHTS: ScoreWeights;
+export interface TierThresholds {
+    readonly high: number;
+    readonly mid: number;
+}
+export declare const DEFAULT_THRESHOLDS: TierThresholds;
+export interface ScoreContext {
+    readonly query: string;
+    readonly now: number;
+    readonly freshnessHalfLifeMs?: number;
+    readonly tokenBudget?: number;
+    readonly weights?: ScoreWeights;
+    readonly thresholds?: TierThresholds;
+    readonly activeDecisionIds?: readonly string[];
+    readonly lexScores?: ReadonlyMap<string, number>;
+    readonly retrievalScores?: ReadonlyMap<string, number>;
+}
+export interface ScoreCandidateOptions {
+    readonly seenTermSets?: readonly ReadonlySet<string>[];
+}
+export declare function scoreFactors(candidate: ContextCandidate, ctx: ScoreContext, opts?: ScoreCandidateOptions): ContextScoreFactors;
+export declare function combineScore(factors: ContextScoreFactors, weights?: ScoreWeights): number;
+export declare function tierFor(score: number, thresholds?: TierThresholds): ContextTier;
+export declare function scoreCandidate(candidate: ContextCandidate, ctx: ScoreContext, opts?: ScoreCandidateOptions): ContextScore;
+export declare function scoreCandidates(candidates: readonly ContextCandidate[], ctx: ScoreContext): readonly ContextScore[];

package/dist/vascend/context-scorer.js

@@ -0,0 +1,162 @@
+// Context Scorer (metodo Danilov, Memory OS).
+//
+// Assegna a ogni ContextCandidate un punteggio multi-fattore PRIMA di inserirlo
+// nel prompt, cosi' che il Context Window Compiler decida cosa entra come corpo
+// (HIGH), cosa come solo handle (MID) e cosa viene escluso (LOW).
+//
+// Formula mentale del documento talos-context:
+//   context_value =
+//       relevance + dependency + trust + freshness + novelty
+//     - conflict_risk - token_cost
+//
+// Modulo PURO e DETERMINISTICO: stessi input -> stesso output, nessun
+// side-effect, nessuna rete, nessun orologio interno (il "now" e' un parametro).
+import { confidenceWeight, estimateCandidateTokens, } from "./context-candidate.js";
+import { tokenize } from "./lexical-search.js";
+export const DEFAULT_WEIGHTS = {
+    relevance: 1.0,
+    dependency: 0.8,
+    trust: 0.6,
+    freshness: 0.5,
+    novelty: 0.4,
+    conflictRisk: 1.0,
+    tokenCost: 0.3,
+};
+export const DEFAULT_THRESHOLDS = { high: 1.2, mid: 0.5 };
+const HOUR_MS = 60 * 60 * 1000;
+const DEFAULT_HALF_LIFE = 72 * HOUR_MS; // 3 giorni
+const DEFAULT_BUDGET = 4_000;
+// --- fattori ----------------------------------------------------------------
+// Rilevanza: usa il punteggio lessicale BM25 (IDF-aware) gia' calcolato dal
+// retriever quando disponibile (segnale piu' forte: i termini rari pesano di
+// piu' di quelli comuni). In assenza, fallback all'overlap binario tra query e
+// (terms+subject+summary) normalizzato sul numero di token di query. In
+// entrambi i casi deterministico.
+function relevanceFactor(candidate, queryTokens, lexScore) {
+    if (typeof lexScore === "number")
+        return clamp01(lexScore);
+    if (!queryTokens.length)
+        return 0;
+    const docTokens = new Set(tokenize(`${candidate.terms.join(" ")} ${candidate.subject} ${candidate.summary}`));
+    if (!docTokens.size)
+        return 0;
+    let hits = 0;
+    for (const q of queryTokens)
+        if (docTokens.has(q))
+            hits += 1;
+    return clamp01(hits / queryTokens.length);
+}
+// Freshness: decadimento esponenziale con half-life. createdAt==0 (sconosciuto)
+// vale neutro 0.5 per non penalizzare candidati senza timestamp.
+function freshnessFactor(candidate, now, halfLife) {
+    if (!candidate.createdAt)
+        return 0.5;
+    const age = Math.max(0, now - candidate.createdAt);
+    return clamp01(Math.pow(0.5, age / halfLife));
+}
+// Novelty: penalizza i candidati molto simili a quelli gia' selezionati
+// (passati in `seenTermSets`). Senza precedenti, novelty piena.
+function noveltyFactor(candidate, seenTermSets) {
+    if (!seenTermSets.length)
+        return 1;
+    const terms = new Set(candidate.terms);
+    if (!terms.size)
+        return 1;
+    let maxOverlap = 0;
+    for (const seen of seenTermSets) {
+        let inter = 0;
+        for (const t of terms)
+            if (seen.has(t))
+                inter += 1;
+        const overlap = inter / terms.size;
+        if (overlap > maxOverlap)
+            maxOverlap = overlap;
+    }
+    return clamp01(1 - maxOverlap);
+}
+// Conflict risk: alto se il candidato e' superseded/archived; medio se
+// contraddice (per status) una decisione attiva piu' recente.
+function conflictFactor(candidate) {
+    if (candidate.status === "superseded")
+        return 1;
+    if (candidate.status === "archived")
+        return 0.7;
+    if (candidate.supersededBy)
+        return 0.8;
+    return 0;
+}
+// Token cost normalizzato sul budget: piu' un candidato e' grosso, piu' costa.
+function tokenCostFactor(candidate, budget) {
+    const tokens = estimateCandidateTokens(candidate, "body");
+    return clamp01(tokens / Math.max(1, budget));
+}
+// Calcola i fattori grezzi di un candidato. Esposto per debug/metriche.
+export function scoreFactors(candidate, ctx, opts = {}) {
+    const queryTokens = tokenize(ctx.query);
+    const halfLife = ctx.freshnessHalfLifeMs && ctx.freshnessHalfLifeMs > 0 ? ctx.freshnessHalfLifeMs : DEFAULT_HALF_LIFE;
+    const budget = ctx.tokenBudget && ctx.tokenBudget > 0 ? ctx.tokenBudget : DEFAULT_BUDGET;
+    const lexScore = ctx.retrievalScores?.get(candidate.id) ?? ctx.lexScores?.get(candidate.id);
+    return {
+        relevance: relevanceFactor(candidate, queryTokens, lexScore),
+        dependency: candidate.dependency ? 1 : 0,
+        trust: confidenceWeight(candidate.trust),
+        freshness: freshnessFactor(candidate, ctx.now, halfLife),
+        novelty: noveltyFactor(candidate, opts.seenTermSets ?? []),
+        conflictRisk: conflictFactor(candidate),
+        tokenCost: tokenCostFactor(candidate, budget),
+    };
+}
+// Combina i fattori con i pesi nello score finale (puo' essere negativo).
+export function combineScore(factors, weights = DEFAULT_WEIGHTS) {
+    return (weights.relevance * factors.relevance +
+        weights.dependency * factors.dependency +
+        weights.trust * factors.trust +
+        weights.freshness * factors.freshness +
+        weights.novelty * factors.novelty -
+        weights.conflictRisk * factors.conflictRisk -
+        weights.tokenCost * factors.tokenCost);
+}
+// Assegna il tier in base allo score e alle soglie.
+export function tierFor(score, thresholds = DEFAULT_THRESHOLDS) {
+    if (score >= thresholds.high)
+        return "high";
+    if (score >= thresholds.mid)
+        return "mid";
+    return "low";
+}
+// Scoring completo di un singolo candidato.
+export function scoreCandidate(candidate, ctx, opts = {}) {
+    const weights = ctx.weights ?? DEFAULT_WEIGHTS;
+    const thresholds = ctx.thresholds ?? DEFAULT_THRESHOLDS;
+    const factors = scoreFactors(candidate, ctx, opts);
+    const score = combineScore(factors, weights);
+    return { candidate, score, factors, tier: tierFor(score, thresholds) };
+}
+// Scoring di un insieme di candidati con NOVELTY incrementale: ordina per
+// score discendente e penalizza i successivi simili ai gia' scelti. Questo da'
+// un ranking deterministico che evita duplicati senza un passo di dedup a parte.
+export function scoreCandidates(candidates, ctx) {
+    // Primo passo: score base (novelty piena) per ottenere un ordine stabile.
+    const base = candidates.map((c) => ({ c, s: scoreCandidate(c, ctx) }));
+    base.sort((a, b) => b.s.score - a.s.score || a.c.id.localeCompare(b.c.id));
+    // Secondo passo: ricalcola con novelty rispetto ai gia' accettati (in ordine).
+    const seen = [];
+    const out = [];
+    for (const { c } of base) {
+        const scored = scoreCandidate(c, ctx, { seenTermSets: seen });
+        out.push(scored);
+        if (scored.tier !== "low")
+            seen.push(new Set(c.terms));
+    }
+    out.sort((a, b) => b.score - a.score || a.candidate.id.localeCompare(b.candidate.id));
+    return out;
+}
+function clamp01(v) {
+    if (Number.isNaN(v))
+        return 0;
+    if (v < 0)
+        return 0;
+    if (v > 1)
+        return 1;
+    return v;
+}

package/dist/vascend/context-search-index.d.ts

@@ -0,0 +1,12 @@
+import type { ContextCandidate } from "./context-candidate.js";
+import { CandidateLinks } from "./context-links.js";
+import { LexicalIndex } from "./lexical-index.js";
+import { type IndexedDoc } from "./lexical-search.js";
+export declare class ContextSearchIndex {
+    readonly candidates: readonly ContextCandidate[];
+    readonly docs: readonly IndexedDoc<ContextCandidate>[];
+    readonly lexical: LexicalIndex<ContextCandidate>;
+    readonly links: CandidateLinks;
+    private readonly texts;
+    constructor(pool: readonly ContextCandidate[], previous?: ContextSearchIndex, dropSuperseded?: boolean);
+}

package/dist/vascend/context-search-index.js

@@ -0,0 +1,25 @@
+import { CandidateLinks } from "./context-links.js";
+import { LexicalIndex } from "./lexical-index.js";
+import { tokenize } from "./lexical-search.js";
+import { activeCandidates } from "./supersession-graph.js";
+export class ContextSearchIndex {
+    candidates;
+    docs;
+    lexical;
+    links;
+    texts;
+    constructor(pool, previous, dropSuperseded = true) {
+        this.candidates = dropSuperseded ? activeCandidates(pool) : pool;
+        const texts = new Map();
+        this.docs = this.candidates.map((candidate) => {
+            const text = candidate.terms.join(" ") + " " + candidate.subject + " " + candidate.summary + " " + candidate.body;
+            const old = previous?.texts.get(candidate.id);
+            const tokens = old?.text === text ? old.tokens : tokenize(text);
+            texts.set(candidate.id, { text, tokens });
+            return { ref: candidate, tokens };
+        });
+        this.texts = texts;
+        this.lexical = new LexicalIndex(this.docs, (candidate) => candidate.id, previous?.lexical);
+        this.links = new CandidateLinks(this.candidates);
+    }
+}

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

@@ -0,0 +1,22 @@
+import { type RetrievedCandidate } from "./context-retriever.js";
+import { ContextSearchIndex } from "./context-search-index.js";
+import type { ContextCandidate } from "./context-candidate.js";
+export interface ContextSnapshotInput {
+    readonly sessionDir: string;
+    readonly scopeId: string;
+    readonly projectKey?: string;
+    readonly indexed?: boolean;
+    readonly planScopeId?: string;
+}
+export interface ContextStoreSnapshot {
+    readonly key: string;
+    readonly signature: string;
+    readonly pool: readonly ContextCandidate[];
+    readonly index?: ContextSearchIndex;
+    packet(maxChars: number): string;
+    retrieve(query: string, limit: number): readonly RetrievedCandidate[];
+}
+/** Legacy callers can inspect the entire directory; runtime signatures use exact dependencies. */
+export declare function storeSignature(sessionDir: string, scopes?: readonly string[]): string;
+export declare function loadContextStoreSnapshot(input: ContextSnapshotInput): ContextStoreSnapshot;
+export declare function invalidateContextSnapshots(): void;