@vascend/talos 0.1.0

package/dist/vascend/recall-planner.js

@@ -0,0 +1,109 @@
+// Recall Planner (metodo Danilov, Memory OS).
+//
+// Prima di rispondere, se la richiesta dipende dal PASSATO, Talos costruisce un
+// piccolo piano di recupero: quali domini interrogare, con quale query, con
+// quale budget e soglia. Questo riduce drasticamente l'allucinazione sul
+// passato ("continua da dove eravamo rimasti" non deve mandare solo il working
+// set: deve recuperare decisioni, task aperti, asset, vincoli).
+//
+// Modulo PURO e deterministico: analizza il testo utente (niente LLM, niente
+// rete) e produce un RecallPlan. La materializzazione (chiamata recall) e' del
+// chiamante.
+import { tokenize } from "./lexical-search.js";
+// Marcatori IT/EN che segnalano dipendenza dal passato/continuita'.
+const PAST_MARKERS = [
+    /\bcontinu[ai]\b/i,
+    /\bripren[dt]/i,
+    /\bdove\s+eravamo\b/i,
+    /\bcom['e]?\s+rimast/i,
+    /\bstato\s+(?:attuale|corrente|precedente)\b/i,
+    /\bla\s+volta\s+(?:scorsa|precedente)\b/i,
+    /\bgia['\s]/i,
+    /\bprecedent/i,
+    /\bavevamo\b/i,
+    /\bricord/i,
+    /\bdecis(?:o|ione|i)\b/i,
+    /\bwhere\s+we\s+left\b/i,
+    /\bprevious(?:ly)?\b/i,
+    /\blast\s+time\b/i,
+    /\bremember\b/i,
+    /\bresume\b/i,
+    /\bso\s+far\b/i,
+];
+// Parole che orientano verso domini specifici.
+const DOMAIN_HINTS = [
+    { re: /\bdecis|decid|scelt|choice|decision/i, domain: "decisions" },
+    { re: /\bnota|note|appunt|dossier/i, domain: "notes" },
+    { re: /\basset|file|immagin|screenshot|image|document/i, domain: "assets" },
+    { re: /\btask|stanz|castell|piano|plan|room|step/i, domain: "plan" },
+    { re: /\bvassall|kingdom|regno|team/i, domain: "kingdom" },
+    { re: /\bstanz|frontier|room|memoria|recall/i, domain: "rooms" },
+];
+const DEFAULT_DOMAINS = ["plan", "decisions", "notes", "rooms", "assets"];
+// Costruisce il piano di recupero. Deterministico.
+export function planRecall(input) {
+    const text = input.userText ?? "";
+    const budget = input.recallBudget && input.recallBudget > 0 ? input.recallBudget : 800;
+    const dependsOnPast = input.forceRecall === true || PAST_MARKERS.some((re) => re.test(text));
+    if (!dependsOnPast) {
+        return {
+            needed: false,
+            domains: [],
+            query: "",
+            budgetTokens: 0,
+            minScore: 0,
+            reason: "richiesta autoconclusiva: nessun riferimento al passato",
+        };
+    }
+    // Domini: quelli suggeriti dai marcatori, con fallback al set di default.
+    const hinted = DOMAIN_HINTS.filter((h) => h.re.test(text)).map((h) => h.domain);
+    const domains = hinted.length ? unique([...hinted, "decisions"]) : DEFAULT_DOMAINS;
+    // Query: termini chiave del testo (rimosse le stop-word) + niente marcatori.
+    const queryTokens = tokenize(text).slice(0, 12);
+    const query = queryTokens.length ? queryTokens.join(" ") : text.trim().slice(0, 120);
+    return {
+        needed: true,
+        domains,
+        query,
+        budgetTokens: budget,
+        minScore: 0.01,
+        reason: "la richiesta dipende dal passato: recupero mirato prima di rispondere",
+    };
+}
+// Formatta il piano come blocco Danilov per la zona "recall" del pack.
+export function formatRecallPlan(plan) {
+    if (!plan.needed)
+        return "";
+    return [
+        "INDICE",
+        "1 = recall_plan",
+        "",
+        "DEFINIZIONI",
+        `@recall[domini]: ${plan.domains.join(", ")}`,
+        `@recall[query]: "${plan.query}"`,
+        `@recall[budget]: ${plan.budgetTokens} token`,
+        `@recall[soglia]: ${plan.minScore}`,
+        `@recall[motivo]: "${plan.reason}"`,
+        "",
+        "OUTPUT: esegui recall sui domini indicati con questa query PRIMA di rispondere; non ricostruire a memoria.",
+    ].join("\n");
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+// Policy operativa "recall prima di indovinare": blocco testuale da includere
+// nel pack (zona recall/tail). Trasforma la memoria lunga in memoria
+// AFFIDABILE: il modello deve recuperare invece di ricostruire a memoria.
+export const RECALL_FIRST_POLICY = [
+    "INDICE",
+    "1 = policy_recall",
+    "",
+    "DEFINIZIONI",
+    "@policy[recall_prima]: se la risposta dipende da fatti passati NON presenti negli Evidence Slots, non ricostruire a memoria",
+    "@policy[azione]: usa recall <id|query> oppure dichiara esplicitamente che serve recupero",
+    "",
+    "RELAZIONI",
+    "@R: @policy[recall_prima] -> risposta_grounded  [ prove prima di affermazioni ]",
+    "",
+    "OUTPUT: niente allucinazioni sul passato; recall o dichiarazione di memoria insufficiente.",
+].join("\n");

package/dist/vascend/requirements.d.ts

@@ -0,0 +1,31 @@
+import type { Harness } from "../core/bootstrap.js";
+export type RequirementPriority = "must" | "should" | "could";
+export interface AcceptanceCriterion {
+    readonly id: string;
+    readonly text: string;
+}
+export interface Requirement {
+    readonly id: string;
+    readonly text: string;
+    readonly priority: RequirementPriority;
+    readonly criteria: readonly AcceptanceCriterion[];
+}
+export interface RequirementChecklist {
+    readonly goal: string;
+    readonly requirements: readonly Requirement[];
+}
+export declare function requirementsEnabled(env: NodeJS.ProcessEnv): boolean;
+export declare function requirementsMax(env: NodeJS.ProcessEnv): number;
+export declare function judgeRequirements(opts: {
+    readonly harness: Harness;
+    readonly goal: string;
+    readonly signal: AbortSignal;
+    readonly env?: NodeJS.ProcessEnv;
+}): Promise<RequirementChecklist>;
+export declare function parseChecklist(goal: string, text: string, max?: number): RequirementChecklist;
+export declare function buildRequirementsBlock(checklist: RequirementChecklist): string;
+export declare function requirementsSummary(checklist: RequirementChecklist): {
+    readonly total: number;
+    readonly must: number;
+    readonly criteria: number;
+};

package/dist/vascend/requirements.js

@@ -0,0 +1,151 @@
+// Estrazione abilitata di default; off via env (parita' con completeness).
+export function requirementsEnabled(env) {
+    const v = (env["TALOS_REQUIREMENTS"] ?? "").trim().toLowerCase();
+    return !(v === "0" || v === "off" || v === "false" || v === "no");
+}
+// Tetto al numero di requisiti estratti (anti-esplosione). Default 12.
+export function requirementsMax(env) {
+    const n = Number(env["TALOS_REQUIREMENTS_MAX"]);
+    return Number.isInteger(n) && n >= 1 ? n : 12;
+}
+const EXTRACTOR_SYSTEM = `# Estrattore di requisiti
+INDICE
+1 = obiettivo
+2 = requisito
+3 = criterio
+
+DEFINIZIONI
+@obiettivo[fonte]: la richiesta dell'utente, da scomporre senza inventare
+@requisito[misurabile]: cosa va consegnato, in forma OSSERVABILE e verificabile; priorita' must/should/could
+@criterio[accettazione]: condizione BINARIA (vera/falsa) che prova il requisito soddisfatto; concreta, non vaga
+@rigore[essenziale]: SOLO requisiti realmente impliciti/espliciti nel goal; niente nice-to-have, niente perfezionismo
+
+RELAZIONI
+@R1: @obiettivo[fonte] -> @requisito[misurabile]  [ scomponi il goal in requisiti misurabili ]
+@R2: @requisito[misurabile] -> @criterio[accettazione]  [ ogni requisito ha 1+ criteri verificabili ]
+
+OUTPUT: SOLO JSON {"requirements": [{"id": "R1", "text": "...", "priority": "must|should|could", "criteria": [{"id": "R1.1", "text": "..."}]}]}. Niente prosa, niente markdown.`;
+// Estrae la checklist dall'obiettivo via LLM. Se non c'e' provider o l'estrazione
+// fallisce, ritorna una checklist vuota (non bloccante).
+export async function judgeRequirements(opts) {
+    const { harness, goal, signal } = opts;
+    const resolved = harness.providers.resolve(harness.config.model);
+    if (!resolved)
+        return { goal, requirements: [] };
+    const max = requirementsMax(opts.env ?? process.env);
+    const user = `OBIETTIVO dell'utente:\n${goal}\n\n` +
+        `Estrai una checklist di al massimo ${max} requisiti MISURABILI, ognuno con i suoi ` +
+        `criteri di accettazione verificabili. Rispondi SOLO JSON ` +
+        `{"requirements": [{"id","text","priority","criteria":[{"id","text"}]}]}.`;
+    try {
+        const res = await resolved.provider.complete({
+            system: EXTRACTOR_SYSTEM,
+            messages: [{ role: "user", content: [{ type: "text", text: user }] }],
+            tools: [],
+            model: resolved.modelId,
+            maxTokens: harness.config.maxTokens,
+            signal,
+            sessionId: `requirements-${harness.session.id}`,
+        });
+        return parseChecklist(goal, res.text, max);
+    }
+    catch {
+        return { goal, requirements: [] }; // in dubbio non bloccare
+    }
+}
+const PRIORITIES = new Set(["must", "should", "could"]);
+function normalizePriority(v) {
+    const s = String(v ?? "").trim().toLowerCase();
+    return PRIORITIES.has(s) ? s : "must";
+}
+function normalizeCriteria(raw, reqId) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const c of raw) {
+        const text = String(c?.text ?? (typeof c === "string" ? c : "")).trim();
+        if (!text)
+            continue;
+        const rawId = String(c?.id ?? "").trim();
+        const id = rawId || `${reqId}.${out.length + 1}`;
+        out.push({ id, text });
+        if (out.length >= 12)
+            break;
+    }
+    return out;
+}
+// Parsing robusto: estrae il primo blocco JSON, normalizza id/priority/criteri,
+// scarta i requisiti senza testo, applica il tetto `max`.
+export function parseChecklist(goal, text, max = 12) {
+    const m = /\{[\s\S]*\}/.exec(text);
+    if (!m)
+        return { goal, requirements: [] };
+    try {
+        const root = JSON.parse(m[0]);
+        const list = Array.isArray(root.requirements) ? root.requirements : [];
+        const requirements = [];
+        for (const r of list) {
+            const obj = r;
+            const text = String(obj?.text ?? "").trim();
+            if (!text)
+                continue;
+            const id = String(obj?.id ?? "").trim() || `R${requirements.length + 1}`;
+            requirements.push({
+                id,
+                text,
+                priority: normalizePriority(obj?.priority),
+                criteria: normalizeCriteria(obj?.criteria, id),
+            });
+            if (requirements.length >= max)
+                break;
+        }
+        return { goal, requirements };
+    }
+    catch {
+        return { goal, requirements: [] };
+    }
+}
+const PRIORITY_TAG = {
+    must: "MUST",
+    should: "SHOULD",
+    could: "COULD",
+};
+// Formatta la checklist in notazione Danilov: utile come blocco di contesto
+// (steer) iniettato all'agente o come `evidence` per il critico di completezza.
+export function buildRequirementsBlock(checklist) {
+    const { goal, requirements } = checklist;
+    if (requirements.length === 0)
+        return "";
+    const defs = [];
+    const rels = [];
+    for (const r of requirements) {
+        const crit = r.criteria.map((c) => `${c.id}: ${c.text}`).join(" ; ");
+        defs.push(`@${r.id}[${PRIORITY_TAG[r.priority]}]: ${r.text}${crit ? ` -> [ ${crit} ]` : ""}`);
+        rels.push(`@R-${r.id}: @${r.id} -> consegna  [ soddisfatto sse tutti i criteri ${r.id}.* sono veri ]`);
+    }
+    return `[VASCEND_REQUISITI]
+INDICE
+1 = goal
+2 = requisiti
+3 = criteri
+
+DEFINIZIONI
+@goal[reale]: "${goal.replace(/"/g, "'").slice(0, 200)}"
+${defs.join("\n")}
+
+RELAZIONI
+${rels.join("\n")}
+
+OUTPUT: usa questa checklist come riferimento OGGETTIVO; il goal e' completo sse ogni requisito MUST ha tutti i criteri di accettazione verificati.`;
+}
+// Conteggi sintetici, comodi per status/log.
+export function requirementsSummary(checklist) {
+    let must = 0;
+    let criteria = 0;
+    for (const r of checklist.requirements) {
+        if (r.priority === "must")
+            must += 1;
+        criteria += r.criteria.length;
+    }
+    return { total: checklist.requirements.length, must, criteria };
+}

package/dist/vascend/reviewer.d.ts

@@ -0,0 +1,9 @@
+import type { VascendState } from "./runtime.js";
+export interface ReviewOptions {
+    readonly enabled: boolean;
+    readonly minRooms: number;
+}
+export declare function reviewOptions(env: NodeJS.ProcessEnv): ReviewOptions;
+export declare function shouldReview(state: VascendState, minRooms: number): boolean;
+export declare function buildRoomMetricsDigest(state: VascendState): string;
+export declare function buildReviewerPrompt(digest: string): string;

package/dist/vascend/reviewer.js

@@ -0,0 +1,93 @@
+export function reviewOptions(env) {
+    const flag = (env["TALOS_REVIEWER"] ?? "").trim().toLowerCase();
+    const enabled = !(flag === "0" || flag === "off" || flag === "false" || flag === "no");
+    const n = Number(env["TALOS_REVIEWER_MIN_ROOMS"]);
+    const minRooms = Number.isFinite(n) && n >= 2 ? n : 5;
+    return { enabled, minRooms };
+}
+function done(c) { return c.tasks.filter((t) => t.status === "completed"); }
+function open(c) { return c.tasks.filter((t) => t.status === "pending" || t.status === "running"); }
+// Vale la pena revisionare? Regno complesso (>= minRooms stanze), con almeno una
+// stanza fatta E almeno una ancora da fare (cosi' la revisione puo' incidere).
+export function shouldReview(state, minRooms) {
+    const rooms = state.kingdom.castles.flatMap((c) => c.tasks);
+    if (rooms.length < minRooms)
+        return false;
+    const anyDone = rooms.some((t) => t.status === "completed");
+    const anyOpen = rooms.some((t) => t.status === "pending" || t.status === "running");
+    return anyDone && anyOpen;
+}
+function fmtMs(ms) {
+    if (ms === undefined)
+        return "?";
+    return ms < 1000 ? `${ms}ms` : `${Math.round(ms / 1000)}s`;
+}
+function fmtTok(n) {
+    if (n === undefined)
+        return "?";
+    if (n >= 1000) {
+        const v = n / 1000;
+        return `${v >= 10 ? Math.round(v) : v.toFixed(1)}k`;
+    }
+    return `${n}`;
+}
+// Digest strutturato delle metriche per il revisore.
+export function buildRoomMetricsDigest(state) {
+    const lines = [];
+    for (const c of state.kingdom.castles) {
+        const d = done(c);
+        const o = open(c);
+        lines.push(`@gruppo[${c.slug}]: titolo="${c.title}", fatte=${d.length}/${c.tasks.length}${c.after ? `, dopo=${c.after}` : ""}`);
+        if (c.notes?.length)
+            lines.push(`  note_gruppo: ${c.notes.join(" | ")}`);
+        for (const t of d) {
+            const note = t.notes?.length ? ` · note: ${t.notes.join(" | ")}` : "";
+            const sk = t.skills?.length ? ` · skill: ${t.skills.join(",")}` : "";
+            lines.push(`  fatta ${t.id} "${t.title}" · ↓${fmtTok(t.tokens)} · ${fmtMs(t.ms)}${sk}${note}`);
+        }
+        for (const t of o) {
+            const sk = t.skills?.length ? ` · skill: ${t.skills.join(",")}` : "";
+            const w = t.weight ? ` · peso ${t.weight}` : "";
+            lines.push(`  da_fare ${t.id} "${t.title}"${w}${sk}`);
+        }
+        // Sintesi metriche del castello.
+        const withTok = d.filter((t) => t.tokens !== undefined);
+        if (withTok.length) {
+            const tot = withTok.reduce((s, t) => s + (t.tokens ?? 0), 0);
+            const avg = Math.round(tot / withTok.length);
+            const top = withTok.reduce((m, t) => ((t.tokens ?? 0) > (m.tokens ?? 0) ? t : m), withTok[0]);
+            lines.push(`  metriche: totale ↓${fmtTok(tot)}, media ↓${fmtTok(avg)}/attivita, piu' costosa ${top.id} (↓${fmtTok(top.tokens)})`);
+        }
+    }
+    return lines.join("\n");
+}
+// Prompt del revisore: analizza le metriche e migliora SOLO le stanze rimaste.
+export function buildReviewerPrompt(digest) {
+    return `[VASCEND_REVISIONE]
+Sei il REVISORE del team (piano di lavoro). NON rifai il lavoro gia' fatto: analizzi
+le attivita completate (token e durata) e le note, e migliori SOLO le attivita rimaste.
+
+INDICE
+1 = metriche
+2 = analisi
+3 = azione
+
+DEFINIZIONI
+@metriche[piano]: digest sotto (attivita fatte con token/durata + attivita da fare)
+@analisi[obiettivo]: trova attivita costose/lente, lavoro ridondante, passi mancanti
+@azione[consentite]: vascend_addtasks (aggiungi attivita rimaste), vascend_note (annota analisi/ordine consigliato sulle attivita o sul gruppo), vascend_skill (abbina skill utili in anticipo). Per il dettaglio di una attivita fatta usa recall.
+
+RELAZIONI
+@R1: @metriche[piano] -> @analisi[obiettivo]  [ leggi prima di agire ]
+@R2: @analisi[obiettivo] -> @azione[consentite]  [ agisci solo sulle attivita da fare ]
+
+REGOLE
+- NON marcare attivita (niente vascend_mark) e NON eseguire il lavoro: solo revisione e riorganizzazione.
+- Sii conciso: poche azioni mirate. Se il piano e' gia' ottimale, dillo in una riga e fermati.
+- Usa le note per indicare l'ORDINE ottimale delle attivita rimaste (non puoi riordinare i bit).
+
+METRICHE
+${digest}
+
+OUTPUT: una breve sintesi in notazione + le azioni (addrooms/note/skill) applicate alle sole attivita rimaste.`;
+}

package/dist/vascend/room-graph.d.ts

@@ -0,0 +1,29 @@
+import type { RoomRecord } from "./room-memory.js";
+export type RoomEdgeRel = "tocca" | "usa";
+export type RoomEdgeKind = "file" | "tool";
+export interface RoomEdge {
+    readonly rel: RoomEdgeRel;
+    readonly kind: RoomEdgeKind;
+    readonly target: string;
+}
+export declare function roomEdges(files: readonly string[], tools: readonly string[]): readonly RoomEdge[];
+export declare function edgesOf(record: RoomRecord): readonly RoomEdge[];
+export declare function filesOf(record: RoomRecord): readonly string[];
+export interface RoomNeighbor {
+    readonly room: string;
+    readonly shared: number;
+    readonly via: readonly string[];
+}
+export declare class RoomGraph {
+    private readonly byTarget;
+    private readonly byRoom;
+    private constructor();
+    static build(records: readonly RoomRecord[]): RoomGraph;
+    targets(room: string): readonly string[];
+    roomsTouching(target: string): readonly string[];
+    neighbors(room: string, limit?: number): readonly RoomNeighbor[];
+}
+export declare function affinity(a: RoomRecord, b: RoomRecord): number;
+export declare function clusterByAffinity(nodes: readonly RoomRecord[], size: number): readonly (readonly RoomRecord[])[];
+export declare function clusterLabel(group: readonly RoomRecord[]): string;
+export declare function topTerms(group: readonly RoomRecord[], limit: number): readonly string[];

package/dist/vascend/room-graph.js

@@ -0,0 +1,242 @@
+// Grafo della memoria delle stanze (metodo Danilov, Memory OS).
+//
+// La gerarchia stanza -> castello -> regno risponde a "dove sta questo nel
+// tempo". Non risponde a "cosa c'entra con cosa": l'unica relazione persistita
+// era `contains`, quindi due stanze che lavorano sullo STESSO file restavano
+// estranee, raggiungibili solo per coincidenza lessicale.
+//
+// Questo modulo aggiunge il secondo asse: gli ARCHI TIPIZZATI.
+//
+//   stanza --tocca--> file        (dai path dei tool call)
+//   stanza --usa-----> tool        (dai nomi dei tool)
+//   stanza --vicina--> stanza      (derivata: 2 hop attraverso un file comune)
+//
+// Serve a due cose, entrambe misurabili:
+//   1) recall che TRAVERSA (chi altro ha toccato questo file?) invece di
+//      sperare che le parole coincidano;
+//   2) rollup per AFFINITA' invece che per ordine di arrivo, cosi' un castello
+//      e' un'unita' di senso e non una fetta di tempo.
+//
+// Modulo PURO: nessun I/O, nessuna dipendenza a runtime, deterministico.
+import { STOP } from "./lexical-search.js";
+// Quanti archi al massimo per stanza e per tipo: un turno che tocca 200 file
+// non deve gonfiare il record ne' dominare il grafo.
+const MAX_EDGES_PER_KIND = 12;
+export function roomEdges(files, tools) {
+    const seen = new Set();
+    const out = [];
+    for (const file of files.slice(0, MAX_EDGES_PER_KIND)) {
+        const target = normalizeTarget(file);
+        if (!target || seen.has(`f:${target}`))
+            continue;
+        seen.add(`f:${target}`);
+        out.push({ rel: "tocca", kind: "file", target });
+    }
+    for (const tool of tools.slice(0, MAX_EDGES_PER_KIND)) {
+        const target = tool.trim();
+        if (!target || seen.has(`t:${target}`))
+            continue;
+        seen.add(`t:${target}`);
+        out.push({ rel: "usa", kind: "tool", target });
+    }
+    return out;
+}
+// Archi di un record. Gli store scritti PRIMA di questa versione non hanno il
+// campo `edges`: li si ricava dal corpo Danilov, cosi' anche le sessioni
+// storiche entrano nel grafo senza migrazione.
+export function edgesOf(record) {
+    if (record.edges && record.edges.length)
+        return record.edges;
+    const files = [];
+    for (const m of record.body.matchAll(/@file\[[^\]]*\]:\s*(.+)/g)) {
+        const value = (m[1] ?? "").trim();
+        if (value)
+            files.push(value);
+    }
+    const tools = [];
+    for (const m of record.body.matchAll(/@tool\[[^\]]*\]:\s*([a-zA-Z0-9_.-]+)\(/g)) {
+        const value = (m[1] ?? "").trim();
+        if (value)
+            tools.push(value);
+    }
+    return roomEdges(files, tools);
+}
+export function filesOf(record) {
+    return edgesOf(record).filter((e) => e.kind === "file").map((e) => e.target);
+}
+// Indice del grafo: file -> stanze che lo toccano, e vicinato a 2 hop.
+export class RoomGraph {
+    byTarget = new Map();
+    byRoom = new Map();
+    constructor(records) {
+        for (const record of records) {
+            if (record.level !== 0)
+                continue; // il grafo vive sulle stanze, non sugli indici
+            const targets = filesOf(record);
+            if (!targets.length)
+                continue;
+            this.byRoom.set(record.room, targets);
+            for (const target of targets) {
+                const list = this.byTarget.get(target);
+                if (list)
+                    list.push(record.room);
+                else
+                    this.byTarget.set(target, [record.room]);
+            }
+        }
+    }
+    static build(records) {
+        return new RoomGraph(records);
+    }
+    targets(room) {
+        return this.byRoom.get(room) ?? [];
+    }
+    roomsTouching(target) {
+        return this.byTarget.get(normalizeTarget(target)) ?? [];
+    }
+    // Vicinato a 2 hop: stanza -> file -> altre stanze. Ordinato per numero di
+    // target condivisi (poi per id, per determinismo).
+    neighbors(room, limit = 8) {
+        const targets = this.byRoom.get(room);
+        if (!targets?.length)
+            return [];
+        const hits = new Map();
+        for (const target of targets) {
+            for (const other of this.byTarget.get(target) ?? []) {
+                if (other === room)
+                    continue;
+                const via = hits.get(other);
+                if (via)
+                    via.push(target);
+                else
+                    hits.set(other, [target]);
+            }
+        }
+        return [...hits.entries()]
+            .map(([id, via]) => ({ room: id, shared: via.length, via: [...via] }))
+            .sort((a, b) => b.shared - a.shared || a.room.localeCompare(b.room))
+            .slice(0, limit);
+    }
+}
+// --- affinita' e clustering --------------------------------------------------
+// Affinita' fra due nodi: meta' dai termini indicizzati, meta' dai file
+// toccati. In [0,1], simmetrica, deterministica.
+export function affinity(a, b) {
+    return 0.5 * jaccard(a.terms, b.terms) + 0.5 * jaccard(filesOf(a), filesOf(b));
+}
+// Raggruppa i nodi in gruppi di ESATTAMENTE `size` per affinita'. Il gruppo
+// parte dal nodo con la massa di affinita' piu' alta (il centro del grappolo
+// piu' denso) e attira i piu' simili; i nodi che avanzano restano fuori.
+// Mantenere la dimensione fissa preserva la garanzia della gerarchia: il
+// contesto vivo resta limitato a ~fanout*livelli voci.
+export function clusterByAffinity(nodes, size) {
+    if (size < 2 || nodes.length < size)
+        return [];
+    const pool = [...nodes];
+    const groups = [];
+    while (pool.length >= size) {
+        // Ancoraggio: il nodo PIU' VECCHIO ancora libero. Provata anche la
+        // partenza dal grappolo piu' denso: e' peggiore (purezza 0.70 contro 0.90
+        // sul bench rollup-quality), perche' svuota il centro e lascia una coda di
+        // avanzi scorrelati. Partire dal piu' vecchio drena l'archivio in ordine e
+        // sfrutta il fatto che il lavoro e' gia' raggruppato nel tempo.
+        const anchor = pool[0];
+        // Crescita per CENTROIDE: a ogni passo entra il nodo piu' affine al gruppo
+        // gia' formato, non al solo ancoraggio. Un gruppo a stella intorno a una
+        // sola stanza raccoglie i suoi vicini anche quando sono scorrelati fra
+        // loro; crescendo sul centroide il grappolo resta coeso.
+        const chosen = [anchor];
+        const rest = pool.filter((n) => n.room !== anchor.room);
+        while (chosen.length < size && rest.length) {
+            let best = 0;
+            let bestScore = -1;
+            rest.forEach((candidate, i) => {
+                const score = chosen.reduce((acc, member) => acc + affinity(member, candidate), 0) / chosen.length;
+                const incumbent = rest[best];
+                if (score > bestScore ||
+                    (score === bestScore &&
+                        (candidate.createdAt < incumbent.createdAt ||
+                            (candidate.createdAt === incumbent.createdAt && candidate.room.localeCompare(incumbent.room) < 0)))) {
+                    best = i;
+                    bestScore = score;
+                }
+            });
+            chosen.push(rest.splice(best, 1)[0]);
+        }
+        const group = chosen.slice().sort((a, b) => a.createdAt - b.createdAt || a.room.localeCompare(b.room));
+        groups.push(group);
+        const taken = new Set(group.map((g) => g.room));
+        for (let i = pool.length - 1; i >= 0; i -= 1) {
+            if (taken.has(pool[i].room))
+                pool.splice(i, 1);
+        }
+    }
+    return groups;
+}
+// Etichetta ONESTA di un gruppo: l'area comune dei file piu' i termini
+// ricorrenti. Sostituisce "titolo del primo figlio + ... +7", che annunciava
+// un castello col nome di un ottavo del suo contenuto.
+export function clusterLabel(group) {
+    const area = commonArea(group.flatMap((r) => filesOf(r)));
+    const terms = topTerms(group, 4);
+    const head = area ? `${area}` : terms.slice(0, 2).join(", ");
+    const tail = terms.length ? terms.join(", ") : group[0]?.title ?? "";
+    if (head && tail && head !== tail)
+        return `${head}: ${tail}`;
+    return head || tail || "gruppo";
+}
+// Termini piu' frequenti nel gruppo (esclusi quelli presenti una volta sola
+// quando il gruppo e' ampio): descrivono il gruppo, non un suo membro.
+export function topTerms(group, limit) {
+    const counts = new Map();
+    for (const record of group) {
+        for (const term of new Set(record.terms)) {
+            if (STOP.has(term))
+                continue;
+            counts.set(term, (counts.get(term) ?? 0) + 1);
+        }
+    }
+    const min = group.length >= 4 ? 2 : 1;
+    return [...counts.entries()]
+        .filter(([, n]) => n >= min)
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .slice(0, limit)
+        .map(([term]) => term);
+}
+// Prefisso di cartella condiviso dalla maggioranza dei file (almeno meta').
+function commonArea(files) {
+    if (!files.length)
+        return "";
+    const counts = new Map();
+    for (const file of files) {
+        const parts = normalizeTarget(file).split("/");
+        parts.pop();
+        for (let i = 1; i <= parts.length; i += 1) {
+            const prefix = parts.slice(0, i).join("/");
+            if (prefix)
+                counts.set(prefix, (counts.get(prefix) ?? 0) + 1);
+        }
+    }
+    const half = files.length / 2;
+    const best = [...counts.entries()]
+        .filter(([, n]) => n >= half)
+        .sort((a, b) => b[0].length - a[0].length || b[1] - a[1] || a[0].localeCompare(b[0]))[0];
+    return best?.[0] ?? "";
+}
+function jaccard(a, b) {
+    if (!a.length && !b.length)
+        return 0;
+    const sa = new Set(a);
+    const sb = new Set(b);
+    let inter = 0;
+    for (const value of sa)
+        if (sb.has(value))
+            inter += 1;
+    const union = new Set([...sa, ...sb]).size;
+    return union ? inter / union : 0;
+}
+// Path normalizzato: separatori POSIX, niente "./" iniziale. Due stanze che
+// hanno scritto "src\\a.ts" e "src/a.ts" devono finire sullo stesso nodo file.
+function normalizeTarget(value) {
+    return value.trim().replace(/\\/g, "/").replace(/^\.\//, "");
+}