@vascend/talos 0.1.0

package/dist/vascend/ramification.js

@@ -0,0 +1,583 @@
+// Ramification — piano di progetto a rami per task a orizzonte lungo.
+//
+// Il modello: un team fondatore progetta un percorso lungo e lo divide in RAMI,
+// uno per ingegnere. Ogni ramo e' una sequenza di NODI, e un nodo NON e' una
+// tacca su una lista: e' una sessione intera di lavoro (un ingegnere piu' uno o
+// piu' agenti che si parlano) che finisce consegnando una TRANSAZIONE — cosa ha
+// prodotto, come lo ha provato, con quale commit. E' per questo che il piano
+// regge su settimane: non vive in una finestra di contesto, vive qui, e una
+// sessione nuova riparte dalla FRONTIERA dei nodi sbloccati.
+//
+// Il cancello, che e' la differenza fra una lista ordinata e una ramificazione:
+// un nodo non si sblocca perche' il precedente e' "finito", ma perche' qualcuno
+// ha giudicato la sua transazione rispetto alla VISIONE del ramo. Tre esiti:
+// passa (sblocca i figli), torna indietro (con le ragioni), oppure il lavoro ha
+// scoperto qualcosa che rende sbagliato il seguito e il FUTURO del ramo va
+// riscritto — cosa che puo' fare solo il team fondatore.
+//
+// Il passato non si tocca. Un nodo consegnato e approvato e' immutabile: una
+// mutazione puo' riscrivere solo cio' che non e' ancora stato consegnato. Senza
+// questa regola un piano lungo si passa la vita a rimettere in discussione
+// quello che aveva gia' verificato.
+//
+// Modulo PURO: ogni operazione ritorna un piano NUOVO, niente I/O, niente date
+// implicite (l'istante si passa). La persistenza e la conversazione stanno
+// altrove.
+const MAX_LOG = 500;
+function clean(value, max) {
+    // I caratteri di controllo si filtrano per CODICE, non con una classe di
+    // caratteri: metterli letterali nel sorgente li rende invisibili a chi legge
+    // e fragili a ogni passaggio di strumento.
+    let out = "";
+    for (const ch of String(value ?? "")) {
+        const code = ch.codePointAt(0) ?? 0;
+        out += code < 0x20 || code === 0x7f ? " " : ch;
+    }
+    return out.replace(/\s+/g, " ").trim().slice(0, max);
+}
+function list(value, max, each) {
+    return (value ?? []).map((item) => clean(item, each)).filter(Boolean).slice(0, max);
+}
+function note(roadmap, entry) {
+    const next = [...roadmap.log, entry];
+    return next.length > MAX_LOG ? next.slice(next.length - MAX_LOG) : next;
+}
+function refuse(roadmap, by, subject, reason, at) {
+    return {
+        ok: false,
+        reason,
+        roadmap: {
+            ...roadmap,
+            log: note(roadmap, { kind: "refused", by: clean(by, 80), subject: clean(subject, 80), detail: reason, at }),
+        },
+    };
+}
+export function createRoadmap(input) {
+    const goal = clean(input.goal, 600);
+    return {
+        goal,
+        acceptance: list(input.acceptance, 12, 200),
+        founders: list(input.founders, 8, 80),
+        branches: [],
+        nodes: {},
+        proposals: [],
+        crosstalk: [],
+        log: [{ kind: "roadmap.created", by: "team", subject: goal.slice(0, 80), detail: goal, at: input.at }],
+        revision: 1,
+    };
+}
+export function addBranch(roadmap, input) {
+    const id = clean(input.id, 60).toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+    if (!id)
+        return refuse(roadmap, input.owner, "", "il ramo ha bisogno di un id", input.at);
+    if (roadmap.branches.some((b) => b.id === id)) {
+        return refuse(roadmap, input.owner, id, `il ramo ${id} esiste gia'`, input.at);
+    }
+    const owner = clean(input.owner, 80);
+    const vision = clean(input.vision, 400);
+    if (!vision)
+        return refuse(roadmap, owner, id, "un ramo senza visione non ha un metro per giudicare i suoi nodi", input.at);
+    const branch = { id, owner, vision, nodes: [] };
+    return {
+        ok: true,
+        roadmap: {
+            ...roadmap,
+            branches: [...roadmap.branches, branch],
+            log: note(roadmap, { kind: "branch.added", by: owner, subject: id, detail: vision, at: input.at }),
+            revision: roadmap.revision + 1,
+        },
+    };
+}
+// Stato calcolato di un nodo non ancora preso: sbloccato solo se OGNI
+// prerequisito e' approvato. E' la regola dell'albero delle abilita'.
+function resolvedState(node, nodes) {
+    if (node.state === "running" || node.state === "review" || node.state === "committed")
+        return node.state;
+    const pending = node.after.filter((id) => nodes[id]?.state !== "committed");
+    if (pending.length)
+        return "locked";
+    return node.state === "returned" ? "returned" : "ready";
+}
+// Ricalcola gli sblocchi dopo ogni cambiamento. Deterministico e idempotente.
+function relock(nodes) {
+    const out = {};
+    for (const [id, node] of Object.entries(nodes)) {
+        const state = resolvedState(node, nodes);
+        out[id] = state === node.state ? node : { ...node, state };
+    }
+    return out;
+}
+export function addNode(roadmap, input) {
+    const id = clean(input.id, 40);
+    const by = clean(input.by, 80);
+    if (!id)
+        return refuse(roadmap, by, "", "il nodo ha bisogno di un id", input.at);
+    if (roadmap.nodes[id])
+        return refuse(roadmap, by, id, `il nodo ${id} esiste gia'`, input.at);
+    const branch = roadmap.branches.find((b) => b.id === clean(input.branch, 60));
+    if (!branch)
+        return refuse(roadmap, by, id, `ramo sconosciuto: ${clean(input.branch, 60)}`, input.at);
+    const mandate = clean(input.mandate, 900);
+    if (!mandate)
+        return refuse(roadmap, by, id, "un nodo senza mandato non e' assegnabile a nessuno", input.at);
+    const after = list(input.after, 12, 40);
+    const ignoto = after.find((ref) => !roadmap.nodes[ref]);
+    if (ignoto)
+        return refuse(roadmap, by, id, `prerequisito inesistente: ${ignoto}`, input.at);
+    const node = {
+        id,
+        branch: branch.id,
+        title: clean(input.title, 160) || id,
+        mandate,
+        acceptance: list(input.acceptance, 10, 200),
+        after,
+        state: "ready",
+        returns: 0,
+    };
+    const nodes = relock({ ...roadmap.nodes, [id]: node });
+    return {
+        ok: true,
+        roadmap: {
+            ...roadmap,
+            nodes,
+            branches: roadmap.branches.map((b) => (b.id === branch.id ? { ...b, nodes: [...b.nodes, id] } : b)),
+            log: note(roadmap, { kind: "node.added", by, subject: id, detail: node.title, at: input.at }),
+            revision: roadmap.revision + 1,
+        },
+    };
+}
+// I nodi che una sessione puo' prendere ADESSO. E' da qui che riparte una
+// sessione nuova: non dal principio del piano, dalla frontiera.
+export function frontier(roadmap) {
+    return Object.values(roadmap.nodes)
+        .filter((node) => node.state === "ready" || node.state === "returned")
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+export function startNode(roadmap, input) {
+    const id = clean(input.id, 40);
+    const by = clean(input.by, 80);
+    const node = roadmap.nodes[id];
+    if (!node)
+        return refuse(roadmap, by, id, `nodo sconosciuto: ${id}`, input.at);
+    if (node.state === "locked") {
+        const mancanti = node.after.filter((ref) => roadmap.nodes[ref]?.state !== "committed");
+        return refuse(roadmap, by, id, `nodo bloccato: prima serve ${mancanti.join(", ")}`, input.at);
+    }
+    if (node.state !== "ready" && node.state !== "returned") {
+        return refuse(roadmap, by, id, `nodo gia' ${node.state}`, input.at);
+    }
+    const sessionId = clean(input.sessionId, 120);
+    if (!sessionId)
+        return refuse(roadmap, by, id, "un nodo e' una sessione: serve l'id della sessione che lo esegue", input.at);
+    const nodes = { ...roadmap.nodes, [id]: { ...node, state: "running", sessionId } };
+    return {
+        ok: true,
+        roadmap: {
+            ...roadmap,
+            nodes,
+            log: note(roadmap, { kind: "node.started", by, subject: id, detail: sessionId, at: input.at }),
+            revision: roadmap.revision + 1,
+        },
+    };
+}
+// Consegna. Senza artefatto e senza prove non e' una consegna: e' una
+// dichiarazione, e su una dichiarazione non si puo' giudicare niente.
+export function submitNode(roadmap, input) {
+    const id = clean(input.id, 40);
+    const by = clean(input.by, 80);
+    const node = roadmap.nodes[id];
+    if (!node)
+        return refuse(roadmap, by, id, `nodo sconosciuto: ${id}`, input.at);
+    if (node.state !== "running")
+        return refuse(roadmap, by, id, `il nodo non e' in esecuzione (${node.state})`, input.at);
+    const artifact = clean(input.transaction?.artifact, 400);
+    const evidence = list(input.transaction?.evidence, 20, 300);
+    if (!artifact)
+        return refuse(roadmap, by, id, "consegna senza artefatto", input.at);
+    if (!evidence.length)
+        return refuse(roadmap, by, id, "consegna senza prove: dichiara cosa hai verificato e come", input.at);
+    const transaction = {
+        artifact,
+        tests: list(input.transaction?.tests, 20, 300),
+        evidence,
+        commit: clean(input.transaction?.commit, 120),
+        at: input.at,
+    };
+    const nodes = { ...roadmap.nodes, [id]: { ...node, state: "review", transaction } };
+    return {
+        ok: true,
+        roadmap: {
+            ...roadmap,
+            nodes,
+            log: note(roadmap, { kind: "node.submitted", by, subject: id, detail: artifact, at: input.at }),
+            revision: roadmap.revision + 1,
+        },
+    };
+}
+// Prima di giudicare si CHIEDE. Nella realta' un capo ramo non decide da solo
+// guardando un diff: sente chi ha fatto il lavoro, o chi conosce il pezzo che
+// il lavoro tocca. Qui resta la traccia della domanda; la risposta arriva
+// parlando, sul canale del team, e finisce nel verdetto come `consulted`.
+export function consultOnNode(roadmap, input) {
+    const id = clean(input.id, 40);
+    const by = clean(input.by, 80);
+    const who = clean(input.who, 80);
+    const node = roadmap.nodes[id];
+    if (!node)
+        return refuse(roadmap, by, id, `nodo sconosciuto: ${id}`, input.at);
+    if (!who)
+        return refuse(roadmap, by, id, "a chi lo chiedi?", input.at);
+    const question = clean(input.question, 600);
+    if (!question)
+        return refuse(roadmap, by, id, "una consultazione senza domanda non serve a nessuno", input.at);
+    return {
+        ok: true,
+        roadmap: {
+            ...roadmap,
+            log: note(roadmap, { kind: "node.consulted", by, subject: `${id}->${who}`, detail: question, at: input.at }),
+            revision: roadmap.revision + 1,
+        },
+    };
+}
+// Il cancello. Giudica CHI possiede il ramo (o un fondatore), rispetto alla
+// visione del ramo e ai criteri del nodo.
+export function judgeNode(roadmap, input) {
+    const id = clean(input.id, 40);
+    const by = clean(input.by, 80);
+    const node = roadmap.nodes[id];
+    if (!node)
+        return refuse(roadmap, by, id, `nodo sconosciuto: ${id}`, input.at);
+    if (node.state !== "review")
+        return refuse(roadmap, by, id, `niente da giudicare: il nodo e' ${node.state}`, input.at);
+    const branch = roadmap.branches.find((b) => b.id === node.branch);
+    const titolare = branch ? branch.owner : "";
+    if (by && titolare && by !== titolare && !roadmap.founders.includes(by)) {
+        return refuse(roadmap, by, id, `il ramo ${node.branch} lo giudica ${titolare}`, input.at);
+    }
+    const reason = clean(input.reason, 600);
+    if (input.decision !== "pass" && !reason) {
+        return refuse(roadmap, by, id, "rimandare indietro senza ragioni non e' un giudizio", input.at);
+    }
+    const consulted = list(input.consulted, 8, 80);
+    const verdict = {
+        decision: input.decision,
+        by,
+        reason,
+        ...(consulted.length ? { consulted } : {}),
+        at: input.at,
+    };
+    if (input.decision === "pass") {
+        const nodes = relock({ ...roadmap.nodes, [id]: { ...node, state: "committed", verdict } });
+        return {
+            ok: true,
+            roadmap: {
+                ...roadmap,
+                nodes,
+                log: note(roadmap, { kind: "node.committed", by, subject: id, detail: reason || node.title, at: input.at }),
+                revision: roadmap.revision + 1,
+            },
+        };
+    }
+    if (input.decision === "return") {
+        const nodes = relock({
+            ...roadmap.nodes,
+            [id]: { ...node, state: "returned", verdict, returns: node.returns + 1 },
+        });
+        return {
+            ok: true,
+            roadmap: {
+                ...roadmap,
+                nodes,
+                log: note(roadmap, { kind: "node.returned", by, subject: id, detail: reason, at: input.at }),
+                revision: roadmap.revision + 1,
+            },
+        };
+    }
+    // replan: il nodo resta consegnato e in attesa. Non e' l'esecutore a
+    // riscrivere il seguito: il team fondatore applica la mutazione.
+    const nodes = { ...roadmap.nodes, [id]: { ...node, verdict } };
+    return {
+        ok: true,
+        roadmap: {
+            ...roadmap,
+            nodes,
+            log: note(roadmap, { kind: "node.replan", by, subject: id, detail: reason, at: input.at }),
+            revision: roadmap.revision + 1,
+        },
+    };
+}
+// Chi esegue PROPONE. Parlando col capo ramo si accorge che il seguito assume
+// qualcosa che non regge: mette la sua riscrittura sul tavolo, con il motivo.
+// Non la applica: la propone, e resta in attesa di una decisione.
+export function proposeMutation(roadmap, input) {
+    const by = clean(input.by, 80);
+    const id = clean(input.id, 60);
+    if (!id)
+        return refuse(roadmap, by, "", "la proposta ha bisogno di un id", input.at);
+    if (roadmap.proposals.some((p) => p.id === id)) {
+        return refuse(roadmap, by, id, `la proposta ${id} esiste gia'`, input.at);
+    }
+    const branch = clean(input.branch, 60);
+    if (branch && !roadmap.branches.some((b) => b.id === branch)) {
+        return refuse(roadmap, by, id, `ramo sconosciuto: ${branch}`, input.at);
+    }
+    const reason = clean(input.reason, 600);
+    if (!reason)
+        return refuse(roadmap, by, id, "una proposta senza il limite che l'ha causata non si puo' valutare", input.at);
+    // Si prova subito a vuoto: una proposta che non si potrebbe comunque
+    // applicare va rifiutata adesso, non dopo che qualcuno l'ha approvata.
+    const prova = mutateFuture(roadmap, { mutation: input.mutation, by: roadmap.founders[0] ?? by, reason, at: input.at });
+    if (!prova.ok)
+        return refuse(roadmap, by, id, `proposta non applicabile: ${prova.reason}`, input.at);
+    const proposal = { id, by, branch, reason, mutation: input.mutation, state: "pending", at: input.at };
+    return {
+        ok: true,
+        roadmap: {
+            ...roadmap,
+            proposals: [...roadmap.proposals, proposal],
+            log: note(roadmap, { kind: "mutation.proposed", by, subject: id, detail: reason, at: input.at }),
+            revision: roadmap.revision + 1,
+        },
+    };
+}
+// Il team fondatore decide sulla proposta. Accettata, la mutazione viene
+// applicata qui: e' l'unico punto in cui il futuro cambia davvero.
+export function resolveProposal(roadmap, input) {
+    const by = clean(input.by, 80);
+    const id = clean(input.id, 60);
+    const proposal = roadmap.proposals.find((p) => p.id === id);
+    if (!proposal)
+        return refuse(roadmap, by, id, `proposta sconosciuta: ${id}`, input.at);
+    if (proposal.state !== "pending")
+        return refuse(roadmap, by, id, `proposta gia' ${proposal.state}`, input.at);
+    if (roadmap.founders.length && !roadmap.founders.includes(by)) {
+        return refuse(roadmap, by, id, "sulle proposte decide il team che ha aperto la ramificazione", input.at);
+    }
+    const reason = clean(input.reason, 600);
+    const segna = (state) => roadmap.proposals.map((p) => (p.id === id ? { ...p, state } : p));
+    if (!input.accept) {
+        if (!reason)
+            return refuse(roadmap, by, id, "rifiutare una proposta senza ragioni non e' una decisione", input.at);
+        return {
+            ok: true,
+            roadmap: {
+                ...roadmap,
+                proposals: segna("rejected"),
+                log: note(roadmap, { kind: "mutation.rejected", by, subject: id, detail: reason, at: input.at }),
+                revision: roadmap.revision + 1,
+            },
+        };
+    }
+    const esito = mutateFuture(roadmap, {
+        mutation: proposal.mutation,
+        by,
+        reason: reason || proposal.reason,
+        at: input.at,
+    });
+    if (!esito.ok)
+        return esito;
+    return {
+        ok: true,
+        roadmap: {
+            ...esito.roadmap,
+            proposals: esito.roadmap.proposals.map((p) => (p.id === id ? { ...p, state: "accepted" } : p)),
+        },
+    };
+}
+// Riscrittura del FUTURO. Solo il team fondatore, e solo su cio' che non e'
+// ancora stato approvato: il passato verificato non si rimette in discussione.
+export function mutateFuture(roadmap, input) {
+    const by = clean(input.by, 80);
+    if (roadmap.founders.length && !roadmap.founders.includes(by)) {
+        return refuse(roadmap, by, "", "il futuro di un ramo lo riscrive il team che lo ha aperto", input.at);
+    }
+    const reason = clean(input.reason, 600);
+    if (!reason)
+        return refuse(roadmap, by, "", "una mutazione senza motivo non e' tracciabile", input.at);
+    let nodes = { ...roadmap.nodes };
+    let branches = roadmap.branches.map((b) => ({ ...b, nodes: [...b.nodes] }));
+    for (const id of list(input.mutation.drop, 40, 40)) {
+        const node = nodes[id];
+        if (!node)
+            return refuse(roadmap, by, id, `nodo sconosciuto: ${id}`, input.at);
+        if (node.state === "committed")
+            return refuse(roadmap, by, id, `${id} e' gia' approvato: il passato non si tocca`, input.at);
+        const dipendenti = Object.values(nodes).filter((other) => other.after.includes(id)).map((other) => other.id);
+        if (dipendenti.length)
+            return refuse(roadmap, by, id, `${id} sblocca ${dipendenti.join(", ")}: togli prima quelli`, input.at);
+        delete nodes[id];
+        branches = branches.map((b) => ({ ...b, nodes: b.nodes.filter((ref) => ref !== id) }));
+    }
+    for (const change of input.mutation.retarget ?? []) {
+        const id = clean(change.id, 40);
+        const node = nodes[id];
+        if (!node)
+            return refuse(roadmap, by, id, `nodo sconosciuto: ${id}`, input.at);
+        if (node.state === "committed")
+            return refuse(roadmap, by, id, `${id} e' gia' approvato: il passato non si tocca`, input.at);
+        const after = change.after ? list(change.after, 12, 40) : node.after;
+        const ignoto = after.find((ref) => ref !== id && !nodes[ref]);
+        if (ignoto)
+            return refuse(roadmap, by, id, `prerequisito inesistente: ${ignoto}`, input.at);
+        if (after.includes(id))
+            return refuse(roadmap, by, id, `${id} non puo' dipendere da se stesso`, input.at);
+        nodes[id] = {
+            ...node,
+            ...(change.mandate ? { mandate: clean(change.mandate, 900) } : {}),
+            ...(change.acceptance ? { acceptance: list(change.acceptance, 10, 200) } : {}),
+            after,
+        };
+    }
+    for (const nuovo of input.mutation.add ?? []) {
+        const id = clean(nuovo.id, 40);
+        if (!id)
+            return refuse(roadmap, by, "", "il nodo ha bisogno di un id", input.at);
+        if (nodes[id])
+            return refuse(roadmap, by, id, `il nodo ${id} esiste gia'`, input.at);
+        const branch = branches.find((b) => b.id === clean(nuovo.branch, 60));
+        if (!branch)
+            return refuse(roadmap, by, id, `ramo sconosciuto: ${clean(nuovo.branch, 60)}`, input.at);
+        const mandate = clean(nuovo.mandate, 900);
+        if (!mandate)
+            return refuse(roadmap, by, id, "un nodo senza mandato non e' assegnabile a nessuno", input.at);
+        const after = list(nuovo.after, 12, 40);
+        const ignoto = after.find((ref) => !nodes[ref]);
+        if (ignoto)
+            return refuse(roadmap, by, id, `prerequisito inesistente: ${ignoto}`, input.at);
+        nodes[id] = {
+            id,
+            branch: branch.id,
+            title: clean(nuovo.title, 160) || id,
+            mandate,
+            acceptance: list(nuovo.acceptance, 10, 200),
+            after,
+            state: "ready",
+            returns: 0,
+        };
+        branch.nodes.push(id);
+    }
+    const ciclo = trovaCiclo(nodes);
+    if (ciclo)
+        return refuse(roadmap, by, ciclo, `la mutazione chiude un anello: ${ciclo}`, input.at);
+    return {
+        ok: true,
+        roadmap: {
+            ...roadmap,
+            nodes: relock(nodes),
+            branches,
+            log: note(roadmap, { kind: "future.mutated", by, subject: "", detail: reason, at: input.at }),
+            revision: roadmap.revision + 1,
+        },
+    };
+}
+// Un anello fra prerequisiti bloccherebbe il piano per sempre senza dirlo: si
+// rifiuta la mutazione, non si scopre a esecuzione ferma.
+function trovaCiclo(nodes) {
+    const stato = new Map();
+    const cammino = [];
+    const visita = (id) => {
+        const marchio = stato.get(id);
+        if (marchio === 2)
+            return "";
+        if (marchio === 1)
+            return [...cammino.slice(cammino.indexOf(id)), id].join(" -> ");
+        stato.set(id, 1);
+        cammino.push(id);
+        for (const ref of nodes[id]?.after ?? []) {
+            if (!nodes[ref])
+                continue;
+            const trovato = visita(ref);
+            if (trovato)
+                return trovato;
+        }
+        cammino.pop();
+        stato.set(id, 2);
+        return "";
+    };
+    for (const id of Object.keys(nodes)) {
+        const trovato = visita(id);
+        if (trovato)
+            return trovato;
+    }
+    return "";
+}
+// --- Il canale fra nodi -----------------------------------------------------
+//
+// Due ingegneri su rami diversi lavorano ognuno nella sua sessione. Quando uno
+// scopre qualcosa che riguarda l'altro deve poterglielo dire, ma il messaggio
+// non puo' arrivare come se venisse dalla stanza accanto: chi legge deve sapere
+// che parla con un'ALTRA sessione, che ha un suo contesto e una sua storia.
+// Per questo l'origine (nodo, ramo, sessione, chi) sta dentro il messaggio e
+// non si puo' omettere.
+const MAX_CROSSTALK = 300;
+export function postAcrossNodes(roadmap, input) {
+    const fromNode = clean(input.fromNode, 40);
+    const who = clean(input.who, 80) || "sessione";
+    const mittente = roadmap.nodes[fromNode];
+    if (!mittente)
+        return refuse(roadmap, who, fromNode, `nodo sconosciuto: ${fromNode}`, input.at);
+    if (!mittente.sessionId) {
+        return refuse(roadmap, who, fromNode, `${fromNode} non e' stato preso da nessuna sessione: non ha una voce`, input.at);
+    }
+    const text = clean(input.text, 900);
+    if (!text)
+        return refuse(roadmap, who, fromNode, "messaggio vuoto", input.at);
+    const to = clean(input.to, 40);
+    if (to && !roadmap.nodes[to] && !roadmap.branches.some((b) => b.id === to)) {
+        return refuse(roadmap, who, fromNode, `destinatario sconosciuto: ${to} (serve un nodo o un ramo)`, input.at);
+    }
+    if (to === fromNode)
+        return refuse(roadmap, who, fromNode, "un nodo non scrive a se stesso", input.at);
+    const message = {
+        seq: (roadmap.crosstalk.at(-1)?.seq ?? 0) + 1,
+        from: { node: fromNode, branch: mittente.branch, session: mittente.sessionId, who },
+        to,
+        text,
+        at: input.at,
+    };
+    const crosstalk = [...roadmap.crosstalk, message];
+    return {
+        ok: true,
+        roadmap: {
+            ...roadmap,
+            crosstalk: crosstalk.length > MAX_CROSSTALK ? crosstalk.slice(crosstalk.length - MAX_CROSSTALK) : crosstalk,
+            revision: roadmap.revision + 1,
+        },
+    };
+}
+// Cosa e' arrivato a un nodo dopo `since`. Non consuma niente: il cursore lo
+// tiene chi legge, cosi' due letture della stessa sessione non si rubano i
+// messaggi a vicenda.
+export function crosstalkFor(roadmap, input) {
+    const node = roadmap.nodes[clean(input.node, 40)];
+    if (!node)
+        return [];
+    const since = Number(input.since) || 0;
+    return roadmap.crosstalk.filter((m) => m.seq > since
+        && m.from.node !== node.id
+        && (!m.to || m.to === node.id || m.to === node.branch));
+}
+// Come si legge un messaggio che arriva da un'altra sessione. La provenienza
+// apre la riga: e' la prima cosa da sapere, non una nota in fondo.
+export function renderCrosstalk(message) {
+    const rotta = message.to ? ` -> ${message.to}` : " -> tutti";
+    return `[altra sessione] ${message.from.who} · nodo ${message.from.node} · ramo ${message.from.branch}`
+        + ` · sessione ${message.from.session}${rotta}: ${message.text}`;
+}
+// Quanto manca, per ramo. Serve a chi riprende dopo giorni: dove siamo, cosa e'
+// approvato, cosa e' fermo e perche'.
+export function progress(roadmap) {
+    return roadmap.branches.map((branch) => {
+        const nodi = branch.nodes.map((id) => roadmap.nodes[id]).filter(Boolean);
+        const corrente = nodi.find((n) => n.state === "running" || n.state === "review")
+            || nodi.find((n) => n.state === "ready" || n.state === "returned");
+        return {
+            branch: branch.id,
+            owner: branch.owner,
+            committed: nodi.filter((n) => n.state === "committed").length,
+            total: nodi.length,
+            current: corrente ? corrente.id : "",
+            blocked: nodi.filter((n) => n.state === "locked").map((n) => n.id),
+        };
+    });
+}

package/dist/vascend/recall-planner.d.ts

@@ -0,0 +1,17 @@
+import type { MemoryDomain } from "./memory-store.js";
+export interface RecallPlan {
+    readonly needed: boolean;
+    readonly domains: readonly MemoryDomain[];
+    readonly query: string;
+    readonly budgetTokens: number;
+    readonly minScore: number;
+    readonly reason: string;
+}
+export interface PlanRecallInput {
+    readonly userText: string;
+    readonly recallBudget?: number;
+    readonly forceRecall?: boolean;
+}
+export declare function planRecall(input: PlanRecallInput): RecallPlan;
+export declare function formatRecallPlan(plan: RecallPlan): string;
+export declare const RECALL_FIRST_POLICY: string;