@vascend/talos 0.1.0

package/dist/vascend/lexical-index.d.ts

@@ -0,0 +1,10 @@
+import { type Bm25Params, type IndexedDoc, type ScoredDoc, type WeightedTerm } from "./lexical-search.js";
+/** Immutable index versions share unchanged documents and posting lists. */
+export declare class LexicalIndex<T> {
+    private readonly documents;
+    private readonly postings;
+    private readonly tokenCount;
+    private readonly fuzzy;
+    constructor(docs: readonly IndexedDoc<T>[], key: (ref: T) => string, previous?: LexicalIndex<T>);
+    score(query: readonly WeightedTerm[], params?: Bm25Params): readonly ScoredDoc<T>[];
+}

package/dist/vascend/lexical-index.js

@@ -0,0 +1,99 @@
+import { DEFAULT_BM25, fuzzyMatch } from "./lexical-search.js";
+/** Immutable index versions share unchanged documents and posting lists. */
+export class LexicalIndex {
+    documents;
+    postings;
+    tokenCount;
+    fuzzy = new Map();
+    constructor(docs, key, previous) {
+        const documents = new Map();
+        const postings = new Map(previous?.postings);
+        const changed = new Map();
+        let tokenCount = previous?.tokenCount ?? 0;
+        const editPosting = (term) => {
+            let posting = changed.get(term);
+            if (!posting) {
+                posting = new Map(postings.get(term));
+                changed.set(term, posting);
+            }
+            return posting;
+        };
+        const remove = (id, doc) => {
+            for (const term of doc.tf.keys())
+                editPosting(term).delete(id);
+            tokenCount -= doc.tokens.length;
+        };
+        for (const doc of docs) {
+            const id = key(doc.ref);
+            const old = previous?.documents.get(id);
+            if (old?.tokens === doc.tokens) {
+                documents.set(id, { ...old, ref: doc.ref });
+                continue;
+            }
+            if (old)
+                remove(id, old);
+            const tf = new Map();
+            for (const [position, term] of doc.tokens.entries()) {
+                const oldTerm = tf.get(term);
+                tf.set(term, { count: (oldTerm?.count ?? 0) + 1, position: oldTerm?.position ?? position });
+            }
+            for (const [term, posting] of tf)
+                editPosting(term).set(id, posting);
+            tokenCount += doc.tokens.length;
+            documents.set(id, { ...doc, tf });
+        }
+        for (const [id, doc] of previous?.documents ?? [])
+            if (!documents.has(id))
+                remove(id, doc);
+        for (const [term, posting] of changed) {
+            if (posting.size)
+                postings.set(term, posting);
+            else
+                postings.delete(term);
+        }
+        this.documents = documents;
+        this.postings = postings;
+        this.tokenCount = tokenCount;
+    }
+    score(query, params = DEFAULT_BM25) {
+        const n = this.documents.size || 1;
+        const avgdl = this.tokenCount / n || 1;
+        const scores = new Map();
+        const idf = (term) => {
+            const df = this.postings.get(term)?.size ?? 0;
+            return Math.log(1 + (n - df + 0.5) / (df + 0.5));
+        };
+        const add = (id, posting, weight, term) => {
+            const doc = this.documents.get(id);
+            const norm = params.k1 * (1 - params.b + params.b * ((doc.tokens.length || 1) / avgdl));
+            const tfNorm = posting.count * (params.k1 + 1) / (posting.count + norm);
+            const contribution = weight * idf(term) * tfNorm;
+            scores.set(id, (scores.get(id) ?? 0) + contribution);
+        };
+        for (const { term, weight } of query) {
+            const exact = this.postings.get(term);
+            for (const [id, posting] of exact ?? [])
+                add(id, posting, weight, term);
+            let similar = this.fuzzy.get(term);
+            if (!similar) {
+                similar = [...this.postings.keys()].filter((word) => word !== term && fuzzyMatch(term, word));
+                if (this.fuzzy.size >= 256)
+                    this.fuzzy.delete(this.fuzzy.keys().next().value);
+                this.fuzzy.set(term, similar);
+            }
+            const best = new Map();
+            for (const word of similar)
+                for (const [id, posting] of this.postings.get(word) ?? []) {
+                    if (exact?.has(id))
+                        continue;
+                    const old = best.get(id);
+                    if (!old || posting.count > old.count || posting.count === old.count && posting.position < old.position) {
+                        best.set(id, { ...posting, term: word });
+                    }
+                }
+            for (const [id, posting] of best)
+                add(id, posting, weight * params.fuzzyWeight, posting.term);
+        }
+        return [...this.documents].map(([id, doc]) => ({ ref: doc.ref, score: scores.get(id) ?? 0 }));
+    }
+}

package/dist/vascend/lexical-search.d.ts

@@ -0,0 +1,29 @@
+export declare function foldAccents(s: string): string;
+export declare function stem(token: string): string;
+export declare function normalizeToken(token: string): string;
+export declare const DEFAULT_SYNONYMS: readonly (readonly string[])[];
+export type SynonymIndex = ReadonlyMap<string, readonly string[]>;
+export declare function buildSynonyms(groups?: readonly (readonly string[])[]): SynonymIndex;
+export interface WeightedTerm {
+    readonly term: string;
+    readonly weight: number;
+}
+export declare function expandQuery(tokens: readonly string[], synonyms: SynonymIndex, synonymWeight?: number): readonly WeightedTerm[];
+export declare const STOP: ReadonlySet<string>;
+export declare function tokenize(s: string): string[];
+export interface Bm25Params {
+    readonly k1: number;
+    readonly b: number;
+    readonly fuzzyWeight: number;
+}
+export declare const DEFAULT_BM25: Bm25Params;
+export interface IndexedDoc<T> {
+    readonly ref: T;
+    readonly tokens: readonly string[];
+}
+export interface ScoredDoc<T> {
+    readonly ref: T;
+    readonly score: number;
+}
+export declare function fuzzyMatch(q: string, t: string): boolean;
+export declare function bm25Score<T>(docs: readonly IndexedDoc<T>[], query: readonly WeightedTerm[], params?: Bm25Params): readonly ScoredDoc<T>[];

package/dist/vascend/lexical-search.js

@@ -0,0 +1,262 @@
+// Motore di ricerca LESSICALE deterministico (BM25-lite) per la memoria stanze.
+//
+// Filosofia: nessun embedding semantico, nessuna dipendenza a runtime, output
+// ripetibile. Aumenta il RICHIAMO su query con parole non perfettamente
+// coincidenti tramite:
+//   1) normalizzazione testuale  -> fold accenti + stemming leggero IT/EN
+//   2) espansione sinonimi        -> tabella bidirezionale configurabile
+//   3) scoring BM25 vero          -> k1/b con normalizzazione per lunghezza doc
+//      + prefix/fuzzy match per termini quasi coincidenti
+//
+// Tutto e' puro e testabile in isolamento: room-memory.ts lo richiama per
+// tokenize/score senza cambiare la sua API pubblica.
+// --- normalizzazione testuale ----------------------------------------------
+// Mappa di folding per i caratteri accentati/diacritici piu' comuni in IT/EN
+// e lingue vicine. Deterministica e senza dipendenze (no Intl/normalize NFD
+// per restare prevedibili su ogni runtime).
+const FOLD = {
+    à: "a", á: "a", â: "a", ã: "a", ä: "a", å: "a", ā: "a", ă: "a",
+    è: "e", é: "e", ê: "e", ë: "e", ē: "e", ĕ: "e", ė: "e", ę: "e",
+    ì: "i", í: "i", î: "i", ï: "i", ī: "i", ĭ: "i",
+    ò: "o", ó: "o", ô: "o", õ: "o", ö: "o", ø: "o", ō: "o", ŏ: "o",
+    ù: "u", ú: "u", û: "u", ü: "u", ū: "u", ŭ: "u",
+    ç: "c", ñ: "n", ý: "y", ÿ: "y", ß: "ss",
+};
+// Abbatte gli accenti su una stringa (case gia' lower). Deterministico.
+export function foldAccents(s) {
+    let out = "";
+    for (const ch of s)
+        out += FOLD[ch] ?? ch;
+    return out;
+}
+// Suffissi IT/EN rimossi in ordine di lunghezza decrescente: stemming LEGGERO
+// (non un Porter completo). Obiettivo: far collassare le forme flesse comuni
+// ("fatturazione"->"fattur", "calcoli"->"calcol") senza sovra-aggregare.
+const SUFFIXES_IT = [
+    "azioni", "azione", "amento", "amenti", "imento", "imenti",
+    "zione", "zioni", "mente", "abile", "ibile", "anza", "enza",
+    "issimo", "issima",
+    "ando", "endo", "are", "ere", "ire", "ato", "ata", "ati", "ate",
+    "uto", "uta", "uti", "ute", "ito", "ita", "iti", "ite",
+    "ire", "ico", "ica", "ici", "iche", "oso", "osa", "osi", "ose",
+];
+const SUFFIXES_EN = [
+    "ization", "isation", "ational", "fulness", "ousness", "iveness",
+    "tion", "sion", "ment", "ness", "able", "ible", "ing", "edly",
+    "ies", "ied", "ous", "ive", "ize", "ise", "er", "ed", "ly", "es", "s",
+];
+// Lunghezza minima della RADICE dopo lo stemming: evita di ridurre parole
+// gia' corte a frammenti inutili (es. non toccare "are" -> "").
+const MIN_STEM = 4;
+// Stemming leggero deterministico: prova i suffissi piu' lunghi prima, IT poi
+// EN, e taglia solo se resta una radice >= MIN_STEM.
+export function stem(token) {
+    let t = token;
+    // I token con separatori (path, kebab) non vanno stemmati: sono identificatori.
+    if (/[._/-]/.test(t))
+        return t;
+    for (const suf of SUFFIXES_IT) {
+        if (t.length - suf.length >= MIN_STEM && t.endsWith(suf))
+            return t.slice(0, -suf.length);
+    }
+    for (const suf of SUFFIXES_EN) {
+        if (t.length - suf.length >= MIN_STEM && t.endsWith(suf))
+            return t.slice(0, -suf.length);
+    }
+    return t;
+}
+// Normalizza un singolo token: lower + fold accenti + stem. Esposto per i test.
+export function normalizeToken(token) {
+    return stem(foldAccents(token.toLowerCase()));
+}
+// --- sinonimi configurabili -------------------------------------------------
+// Gruppi di sinonimi: ogni gruppo e' un insieme di termini equivalenti per la
+// ricerca. La tabella d'espansione e' BIDIREZIONALE (ogni termine del gruppo
+// espande a tutti gli altri). I termini sono gia' normalizzati (stem+fold) per
+// allinearsi al matching. Configurabile: passa gruppi extra a buildSynonyms.
+//
+// Pensati per il dominio coding/Danilov in IT/EN cosi' una query in una lingua
+// trova stanze nell'altra ("file"<->"documento", "errore"<->"bug").
+export const DEFAULT_SYNONYMS = [
+    ["file", "documento", "doc"],
+    ["errore", "error", "bug", "difetto", "guasto"],
+    ["correggi", "fix", "ripara", "sistema", "risolvi"],
+    ["test", "prova", "verifica", "collaudo"],
+    ["funzione", "function", "metodo", "method"],
+    ["cancella", "elimina", "rimuovi", "delete", "remove"],
+    ["aggiungi", "inserisci", "add", "insert"],
+    ["cerca", "ricerca", "search", "trova", "find"],
+    ["memoria", "memory", "ricordo", "recall"],
+    ["stanza", "room", "castello", "castle"],
+    ["calcolo", "calcola", "computa", "compute", "conteggio"],
+    ["magazzino", "giacenza", "inventario", "inventory", "scorta"],
+    ["fattura", "fatturazione", "invoice", "billing"],
+    ["utente", "user", "account", "profilo"],
+    ["configura", "configurazione", "config", "imposta", "setting"],
+    ["server", "backend", "servizio", "service"],
+    ["pagina", "page", "schermata", "view", "vista"],
+];
+export function buildSynonyms(groups = DEFAULT_SYNONYMS) {
+    const idx = new Map();
+    for (const group of groups) {
+        const norm = [...new Set(group.map((t) => normalizeToken(t)).filter(Boolean))];
+        for (const term of norm) {
+            const set = idx.get(term) ?? new Set();
+            for (const other of norm)
+                if (other !== term)
+                    set.add(other);
+            idx.set(term, set);
+        }
+    }
+    // Congela in array ordinati (determinismo dell'output).
+    const out = new Map();
+    for (const [k, v] of idx)
+        out.set(k, [...v].sort());
+    return out;
+}
+export function expandQuery(tokens, synonyms, synonymWeight = 0.6) {
+    const weight = new Map();
+    const bump = (t, w) => {
+        if (!t)
+            return;
+        weight.set(t, Math.max(weight.get(t) ?? 0, w));
+    };
+    for (const tok of tokens) {
+        bump(tok, 1);
+        for (const syn of synonyms.get(tok) ?? [])
+            bump(syn, synonymWeight);
+    }
+    return [...weight.entries()]
+        .map(([term, w]) => ({ term, weight: w }))
+        .sort((a, b) => (b.weight - a.weight) || a.term.localeCompare(b.term));
+}
+// --- tokenizzazione ---------------------------------------------------------
+// Stop-word IT/EN: rumore per l'indice lessicale. Condivisa col formato dei
+// record (room-memory importa STOP da qui per restare allineato).
+export const STOP = new Set([
+    // EN
+    "the", "and", "for", "this", "that", "with", "from", "into", "you", "are",
+    // IT articoli/preposizioni/congiunzioni comuni (rumore per l'INDICE)
+    "il", "lo", "la", "le", "gli", "un", "uno", "una", "di", "da", "in", "su",
+    "al", "allo", "alla", "ai", "agli", "alle", "del", "dello", "della", "dei",
+    "degli", "delle", "nel", "nella", "che", "con", "per", "non", "ed", "tra",
+    "fra", "come", "piu", "gia", "poi", "anche", "ogni", "questo", "questa",
+    // IT verbi/filler ricorrenti nei prompt (azione generica, non concetto)
+    "crea", "creare", "fai", "fare", "usa", "usare", "usando", "aggiungi",
+    "aggiungere", "elenca", "elencare", "leggi", "leggere", "scrivi", "scrivere",
+    "modifica", "modificare", "chiamato", "chiamata", "dentro", "parola", "parole",
+    "strumento", "niente", "prosa", "quindi", "vuoi", "deve", "essere",
+    // troncamenti di preposizioni articolate apostrofate (dell', all', nell', ...)
+    "dell", "all", "nell", "sull", "dall", "quell", "un'",
+]);
+// Tokenizza GREZZO: lower + estrazione lessemi, senza normalizzazione. Mantiene
+// la stessa classe di caratteri del tokenizer storico (path, kebab, numeri).
+function rawTokens(s) {
+    return s.toLowerCase().match(/[a-z0-9_./-]{2,}/g) ?? [];
+}
+// Tokenizza per l'INDICE/ricerca: grezzo -> filtro STOP (sulla forma foldata)
+// -> normalizzazione (fold + stem). Lo STOP-check usa la forma foldata cosi'
+// "piu'"/"piu" e "gia"/"già" vengono filtrati comunque.
+export function tokenize(s) {
+    const out = [];
+    for (const raw of rawTokens(s)) {
+        const folded = foldAccents(raw);
+        if (STOP.has(folded))
+            continue;
+        const norm = stem(folded);
+        if (norm.length >= 2)
+            out.push(norm);
+    }
+    return out;
+}
+export const DEFAULT_BM25 = { k1: 1.5, b: 0.75, fuzzyWeight: 0.45 };
+// Distanza di edit limitata (Levenshtein con cutoff): determina se due token
+// "quasi coincidono". Cutoff piccolo -> deterministico ed economico.
+function withinEditDistance(a, b, max) {
+    if (a === b)
+        return true;
+    const la = a.length;
+    const lb = b.length;
+    if (Math.abs(la - lb) > max)
+        return false;
+    // DP a una riga.
+    let prev = Array.from({ length: lb + 1 }, (_, j) => j);
+    for (let i = 1; i <= la; i += 1) {
+        const curr = [i];
+        let rowMin = i;
+        for (let j = 1; j <= lb; j += 1) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            const v = Math.min((prev[j] ?? 0) + 1, (curr[j - 1] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
+            curr[j] = v;
+            if (v < rowMin)
+                rowMin = v;
+        }
+        if (rowMin > max)
+            return false; // early exit: nessuna cella sotto soglia
+        prev = curr;
+    }
+    return (prev[lb] ?? Infinity) <= max;
+}
+// Decide se un token di query "matcha fuzzy" un token di documento: prefisso
+// (uno e' prefisso dell'altro, len>=4) oppure edit-distance 1 per token >=5.
+// Pensato per termini quasi coincidenti (refusi, plurali sfuggiti allo stem).
+export function fuzzyMatch(q, t) {
+    if (q.length >= 4 && (t.startsWith(q) || q.startsWith(t)))
+        return true;
+    if (Math.min(q.length, t.length) >= 5)
+        return withinEditDistance(q, t, 1);
+    return false;
+}
+// BM25 deterministico su documenti pre-tokenizzati e query pesata (sinonimi).
+// Per ogni termine di query: match ESATTO a peso pieno; in assenza, il miglior
+// match FUZZY a peso ridotto (fuzzyWeight). idf clampato a >= 0.
+export function bm25Score(docs, query, params = DEFAULT_BM25) {
+    const n = docs.length || 1;
+    const { k1, b, fuzzyWeight } = params;
+    // df e avgdl in un passo.
+    const df = new Map();
+    let totalLen = 0;
+    const tfs = docs.map((d) => {
+        const tf = new Map();
+        for (const t of d.tokens)
+            tf.set(t, (tf.get(t) ?? 0) + 1);
+        for (const t of tf.keys())
+            df.set(t, (df.get(t) ?? 0) + 1);
+        totalLen += d.tokens.length;
+        return tf;
+    });
+    const avgdl = totalLen / n || 1;
+    // idf "lite" non-negativo: BM25 con +1 dentro il log per evitare valori <0.
+    const idf = (term) => Math.log(1 + (n - (df.get(term) ?? 0) + 0.5) / ((df.get(term) ?? 0) + 0.5));
+    const out = docs.map((d, i) => {
+        const tf = tfs[i];
+        const dl = d.tokens.length || 1;
+        const norm = k1 * (1 - b + b * (dl / avgdl));
+        let score = 0;
+        for (const { term, weight } of query) {
+            let f = tf.get(term) ?? 0;
+            let qIdf = idf(term);
+            let effWeight = weight;
+            if (!f) {
+                // Nessun match esatto: cerca il miglior match fuzzy nel documento.
+                let bestF = 0;
+                let bestTerm = "";
+                for (const [docTerm, count] of tf) {
+                    if (fuzzyMatch(term, docTerm) && count > bestF) {
+                        bestF = count;
+                        bestTerm = docTerm;
+                    }
+                }
+                if (!bestF)
+                    continue;
+                f = bestF;
+                qIdf = idf(bestTerm);
+                effWeight = weight * fuzzyWeight;
+            }
+            const tfNorm = (f * (k1 + 1)) / (f + norm);
+            score += effWeight * qIdf * tfNorm;
+        }
+        return { ref: d.ref, score };
+    });
+    return out;
+}

package/dist/vascend/long-term-context.d.ts

@@ -0,0 +1,51 @@
+export interface VisionFeatureLike {
+    readonly title?: string;
+    readonly text?: string;
+    readonly priority?: "core" | "important" | "optional" | "must" | "should" | "could" | string;
+    readonly status?: "proposed" | "agreed" | "built" | "dropped" | string;
+    readonly done?: boolean;
+}
+export interface VisionValueLike {
+    readonly statement?: string;
+    readonly beneficiary?: string;
+    readonly metric?: string;
+}
+export interface VisionAssetRefLike {
+    readonly id?: string;
+    readonly name?: string;
+    readonly kind?: "image" | "file" | "snippet" | string;
+}
+export interface VisionLike {
+    readonly id?: string;
+    readonly taskId?: string;
+    readonly goal?: string;
+    readonly finalGoal?: string;
+    readonly objective?: string;
+    readonly value?: string | VisionValueLike;
+    readonly features?: readonly (string | VisionFeatureLike)[];
+    readonly constraints?: readonly string[];
+    readonly nonGoals?: readonly string[];
+    readonly assets?: readonly VisionAssetRefLike[];
+    readonly notes?: readonly string[];
+}
+export interface NormalizedVision {
+    readonly finalGoal: string;
+    readonly value: string;
+    readonly features: readonly string[];
+    readonly constraints: readonly string[];
+    readonly assets: readonly string[];
+    readonly notes: readonly string[];
+}
+export declare function visionHasContent(v: NormalizedVision): boolean;
+export declare function normalizeVision(vision: VisionLike | null | undefined): NormalizedVision;
+export interface ImmediateContext {
+    readonly goal?: string;
+    readonly castle?: string;
+    readonly room?: string;
+}
+export interface LongTermContextInput {
+    readonly vision?: VisionLike | null;
+    readonly immediate?: ImmediateContext;
+}
+export declare function buildLongTermContextBlock(input: LongTermContextInput): string;
+export declare function injectLongTermContext(prompt: string, input: LongTermContextInput): string;

package/dist/vascend/long-term-context.js

@@ -0,0 +1,194 @@
+// Provider di CONTESTO A LUNGO TERMINE (metodo Danilov).
+//
+// Inietta nei prompt la VISION finale di un task -- l'obiettivo ultimo, il
+// valore atteso, le funzionalita' desiderate -- tenendola SEPARATA dagli
+// obiettivi IMMEDIATI di stanze e castelli. La distinzione e' il cuore di
+// questo modulo:
+//
+//   - GOAL IMMEDIATO (momentaneo): cosa si sta facendo adesso, nella stanza o
+//     nel castello corrente. E' volatile, cambia a ogni passo.
+//   - VISION FINALE (a lungo termine): perche' lo si sta facendo, dove si vuole
+//     arrivare. E' stabile, sopravvive ai singoli passi e li orienta.
+//
+// Il provider produce un BLOCCO di contesto in notazione Danilov che il
+// wrapper di prompt antepone all'input, marcando chiaramente i due piani cosi'
+// che il modello non confonda il "qui e ora" con la "stella polare".
+//
+// Modulo PURO: nessun side-effect, nessuna dipendenza rigida. La forma dati
+// Vision e' consumata STRUTTURALMENTE (duck-typed) tramite VisionLike, in modo
+// da non dipendere dal modulo vision-schema finche' non e' mergiato; quando lo
+// sara', VisionLike combaciera' (per struttura) con il tipo Vision reale.
+import { sanitizeText } from "../core/text-sanitize.js";
+// Vera se la Vision normalizzata porta almeno un'informazione utile.
+export function visionHasContent(v) {
+    return Boolean(v.finalGoal ||
+        v.value ||
+        v.features.length ||
+        v.constraints.length ||
+        v.assets.length ||
+        v.notes.length);
+}
+// ---------------------------------------------------------------------------
+// Normalizzazioni difensive.
+// ---------------------------------------------------------------------------
+function oneLine(value) {
+    return sanitizeText(value).replace(/\s+/g, " ").trim();
+}
+function escapeValue(value) {
+    return oneLine(value).replace(/"/g, "'");
+}
+function clip(value, max) {
+    const s = oneLine(value);
+    return s.length > max ? s.slice(0, max - 1).trimEnd() + "…" : s;
+}
+function firstNonEmpty(...vals) {
+    for (const v of vals) {
+        const t = (v ?? "").trim();
+        if (t)
+            return t;
+    }
+    return "";
+}
+const KNOWN_PRIORITIES = new Set(["core", "important", "optional", "must", "should", "could"]);
+function featureText(f) {
+    if (typeof f === "string")
+        return oneLine(f);
+    // status 'dropped' = funzionalita' scartata: non fa parte della visione.
+    const status = (f.status ?? "").trim().toLowerCase();
+    if (status === "dropped")
+        return "";
+    const text = oneLine(f.title ?? f.text ?? "");
+    if (!text)
+        return "";
+    const pr = (f.priority ?? "").trim().toLowerCase();
+    const tag = KNOWN_PRIORITIES.has(pr) ? ` (${pr})` : "";
+    const built = f.done || status === "built" ? " [fatto]" : "";
+    return `${text}${tag}${built}`;
+}
+// Estrae il testo del valore atteso da stringa o VisionValue {statement,...}.
+function valueText(value) {
+    if (!value)
+        return "";
+    if (typeof value === "string")
+        return oneLine(value);
+    const stmt = oneLine(value.statement ?? "");
+    const extra = [];
+    if (value.beneficiary)
+        extra.push(`per ${oneLine(value.beneficiary)}`);
+    if (value.metric)
+        extra.push(`metrica: ${oneLine(value.metric)}`);
+    if (!stmt)
+        return extra.join(", ");
+    return extra.length ? `${stmt} (${extra.join(", ")})` : stmt;
+}
+function assetText(a) {
+    const name = oneLine(a.name ?? a.id ?? "");
+    if (!name)
+        return "";
+    const kind = (a.kind ?? "").trim();
+    return kind ? `${name} (${kind})` : name;
+}
+function cleanList(items, max) {
+    if (!items)
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const raw of items) {
+        const t = oneLine(raw);
+        if (!t)
+            continue;
+        const key = t.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(t);
+        if (out.length >= max)
+            break;
+    }
+    return out;
+}
+// Normalizza una VisionLike (o assente) nella vista interna pulita.
+export function normalizeVision(vision) {
+    if (!vision) {
+        return { finalGoal: "", value: "", features: [], constraints: [], assets: [], notes: [] };
+    }
+    const finalGoal = clip(firstNonEmpty(vision.goal, vision.finalGoal, vision.objective), 240);
+    const value = clip(valueText(vision.value), 240);
+    const features = cleanList((vision.features ?? []).map(featureText), 8);
+    // constraints + nonGoals confluiscono nei "vincoli" (sono entrambi paletti).
+    const constraints = cleanList([...(vision.constraints ?? []), ...(vision.nonGoals ?? []).map((g) => `non-goal: ${g}`)], 6);
+    const assets = cleanList((vision.assets ?? []).map(assetText), 6);
+    const notes = cleanList(vision.notes ?? [], 4);
+    return { finalGoal, value, features, constraints, assets, notes };
+}
+// Costruisce il blocco. Ritorna stringa VUOTA se non c'e' Vision con contenuto:
+// in tal caso il wrapper non aggiunge nulla (degrado con grazia, niente rumore).
+export function buildLongTermContextBlock(input) {
+    const v = normalizeVision(input.vision);
+    if (!visionHasContent(v))
+        return "";
+    const imm = input.immediate ?? {};
+    const immGoal = clip(imm.goal ?? "", 200);
+    const immCastle = oneLine(imm.castle ?? "");
+    const immRoom = oneLine(imm.room ?? "");
+    const hasImmediate = Boolean(immGoal || immCastle || immRoom);
+    const lines = [];
+    lines.push("[VASCEND_VISION]");
+    lines.push("INDICE");
+    lines.push("1 = vision");
+    lines.push("2 = immediato");
+    lines.push("3 = separazione");
+    lines.push("");
+    lines.push("DEFINIZIONI");
+    // Piano 1: la VISION finale (a lungo termine).
+    lines.push(`@vision[finale]: stella_polare, stabile${v.finalGoal ? `, goal="${escapeValue(v.finalGoal)}"` : ""}`);
+    if (v.value)
+        lines.push(`@vision[valore]: "${escapeValue(v.value)}"`);
+    if (v.features.length) {
+        lines.push(`@vision[funzionalita]: ${v.features.map((f) => `"${escapeValue(f)}"`).join(", ")}`);
+    }
+    if (v.constraints.length) {
+        lines.push(`@vision[vincoli]: ${v.constraints.map((c) => `"${escapeValue(c)}"`).join(", ")}`);
+    }
+    if (v.assets.length) {
+        lines.push(`@vision[asset_esempio]: ${v.assets.map((a) => `"${escapeValue(a)}"`).join(", ")}`);
+    }
+    if (v.notes.length) {
+        lines.push(`@vision[note]: ${v.notes.map((n) => `"${escapeValue(n)}"`).join(", ")}`);
+    }
+    // Piano 2: il goal IMMEDIATO (momentaneo), esplicitamente distinto.
+    if (hasImmediate) {
+        const parts = ["momentaneo, volatile"];
+        if (immGoal)
+            parts.push(`goal="${escapeValue(immGoal)}"`);
+        if (immCastle)
+            parts.push(`gruppo="${escapeValue(immCastle)}"`);
+        if (immRoom)
+            parts.push(`attivita="${escapeValue(immRoom)}"`);
+        lines.push(`@immediato[corrente]: ${parts.join(", ")}`);
+    }
+    else {
+        lines.push("@immediato[corrente]: momentaneo, volatile, valore=non_specificato");
+    }
+    lines.push("");
+    lines.push("RELAZIONI");
+    lines.push("@R1: @immediato[corrente] -> @vision[finale]  [ il goal momentaneo SERVE la visione, non la sostituisce ]");
+    lines.push("@R2: @vision[finale] -> @immediato[corrente]  [ la visione ORIENTA ogni passo, resta stabile mentre i goal cambiano ]");
+    lines.push("");
+    lines.push("OUTPUT: tieni la VISION finale come stella polare stabile e DISTINTA dal goal immediato; ogni decisione di attivita/gruppo deve avvicinare la visione senza confondersi con essa.");
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Integrazione: antepone il blocco Vision a un prompt gia' costruito.
+//
+// Pensato per essere chiamato da wrapVascendPrompt (runtime.ts): riceve il
+// prompt "immediato" gia' formato (GOAL momentaneo + INPUT_UTENTE) e gli
+// premette, come piano separato, il contesto a lungo termine. Se non c'e'
+// Vision con contenuto, ritorna il prompt invariato (nessun rumore).
+// ---------------------------------------------------------------------------
+export function injectLongTermContext(prompt, input) {
+    const block = buildLongTermContextBlock(input);
+    if (!block)
+        return prompt;
+    return `${block}\n\n${prompt}`;
+}