@vascend/talos 0.1.0

package/dist/vascend/dev-context-layout.js

@@ -0,0 +1,262 @@
+// Dev Context Layout (metodo Danilov, Memory OS) -- layout specializzato per
+// il lavoro di SVILUPPO del Context Window Compiler.
+//
+// Il layout canonico (attention-layout) e' generico. Quando l'agente opera su
+// codice, l'attenzione va orchestrata diversamente: contano la missione
+// TECNICA, i vincoli NON negoziabili, le decisioni ARCHITETTURALI attive, il
+// CODE GRAPH caldo (simboli/file rilevanti), gli ERRORI e i TEST recenti, le
+// prove citabili (evidence), il PATCH PLAN in corso, il turno utente e infine
+// un tail anchor che ricorda la PROSSIMA AZIONE e i TEST OBBLIGATORI da far
+// passare prima di considerare il lavoro finito.
+//
+// Ordine delle zone dev (testa -> coda), anti "lost-in-the-middle":
+//
+//   1. System invariants        (testa, non comprimibile)
+//   2. Dev Mission Anchor        (missione tecnica + definizione di "done")
+//   3. Vincoli non negoziabili   (build/test/stile che non si possono violare)
+//   4. Decisioni architetturali  (scelte attive che vincolano il codice)
+//   5. Code Graph caldo          (simboli/file/moduli rilevanti al turno)
+//   6. Errori e test recenti     (failure, stacktrace, test rossi)
+//   7. Evidence Slots            (prove citabili, corpo)
+//   8. Patch Plan                (passi di modifica pianificati/in corso)
+//   9. Recall Handles            (handle richiamabili a richiesta)
+//  10. Tool State                (output recenti, file aperti)
+//  11. User Turn                 (richiesta corrente)
+//  12. Dev Tail Anchor           (coda: prossima azione + test obbligatori)
+//
+// Modulo PURO: assembla stringhe gia' pronte / categorizza candidati gia'
+// raccolti. Nessuna lettura degli store qui (vedi dev-context-compiler-side).
+// Ordine canonico delle zone dev. Mission/constraints/decisions in testa
+// (vincolano tutto), user/tail in coda (ripresi prima della generazione).
+export const DEV_ZONE_ORDER = [
+    "system",
+    "mission",
+    "constraints",
+    "decisions",
+    "codegraph",
+    "failures",
+    "evidence",
+    "patchplan",
+    "recall",
+    "tool",
+    "user",
+    "tail",
+];
+// Intestazioni Danilov per zona (commenti del pack dev).
+const DEV_ZONE_HEADER = {
+    system: "[DEV:SYSTEM_INVARIANTS]",
+    mission: "[DEV:MISSION_TECNICA]",
+    constraints: "[DEV:VINCOLI_NON_NEGOZIABILI]",
+    decisions: "[DEV:DECISIONI_ARCHITETTURALI]",
+    codegraph: "[DEV:CODE_GRAPH_CALDO]",
+    failures: "[DEV:ERRORI_E_TEST]",
+    evidence: "[DEV:EVIDENCE_SLOTS]",
+    patchplan: "[DEV:PATCH_PLAN]",
+    recall: "[DEV:RECALL_HANDLES]",
+    tool: "[DEV:TOOL_STATE]",
+    user: "[DEV:USER_TURN]",
+    tail: "[DEV:TAIL_ANCHOR]",
+};
+export function buildDevMissionAnchor(input) {
+    const lines = ["INDICE", "1 = missione", "2 = stack", "3 = ambito", "4 = done", "", "DEFINIZIONI"];
+    lines.push(`@missione[tecnica]: "${esc(input.goal)}"`);
+    if (input.stack?.length) {
+        lines.push(`@stack[attivo]: ${input.stack.map((s) => esc(s)).join(", ")}`);
+    }
+    if (input.scope?.length) {
+        lines.push(`@ambito[moduli]: ${input.scope.map((s) => esc(s)).join(", ")}`);
+    }
+    if (input.done)
+        lines.push(`@done[definizione]: "${esc(input.done)}"`);
+    lines.push("", "OUTPUT: la missione tecnica e' la bussola; non uscire dall'ambito senza motivo.");
+    return lines.join("\n");
+}
+export function buildDevTailAnchor(input) {
+    const lines = [
+        "INDICE",
+        "1 = missione",
+        "2 = vincoli",
+        "3 = decisioni",
+        "4 = azione",
+        "5 = test_obbligatori",
+        "",
+        "DEFINIZIONI",
+    ];
+    lines.push(`@missione[ora]: "${esc(input.goal)}"`);
+    if (input.constraints?.length) {
+        lines.push(`@vincoli[ricorda]: ${input.constraints.map((c) => `"${esc(c)}"`).join(", ")}`);
+    }
+    if (input.activeDecisions?.length) {
+        lines.push(`@decisioni[attive]: ${input.activeDecisions.map((d) => `"${esc(d)}"`).join(", ")}`);
+    }
+    if (input.nextAction)
+        lines.push(`@azione[adesso]: "${esc(input.nextAction)}"`);
+    if (input.requiredTests?.length) {
+        lines.push(`@test[obbligatori]: ${input.requiredTests.map((t) => `"${esc(t)}"`).join(", ")}`);
+    }
+    if (input.recallPolicy) {
+        lines.push("@recall[regola]: se dipende dal passato e manca tra le prove, usa recall, NON indovinare");
+    }
+    lines.push("", "OUTPUT: esegui @azione restando dentro @vincoli e @decisioni; NON dichiarare finito finche' @test[obbligatori] non passano.");
+    return lines.join("\n");
+}
+// Termini-spia per ciascuna categoria (matching lessicale, case-insensitive).
+const FAILURE_TERMS = ["test", "tests", "fail", "failure", "failed", "error", "errore", "stacktrace", "assert", "regression"];
+const PATCH_TERMS = ["patch", "diff", "hunk", "changeset", "edit", "refactor", "migration"];
+const CODEGRAPH_TERMS = ["symbol", "simbolo", "function", "funzione", "class", "classe", "module", "modulo", "import", "export", "graph", "grafo", "dependency", "dipendenza", "ref", "call"];
+// Domini-spia per categoria (un peer puo' emettere su un dominio dedicato).
+const FAILURE_DOMAINS = new Set(["tests", "test", "failures", "ci"]);
+const PATCH_DOMAINS = new Set(["patch", "patches", "patchplan"]);
+const CODEGRAPH_DOMAINS = new Set(["code", "codegraph", "graph", "symbols"]);
+// Categorizza un singolo candidato. Priorita': decisioni architetturali >
+// errori/test > patch plan > code graph > evidence generica. La priorita'
+// previene che un candidato finisca in due zone (es. una decision con term
+// "refactor" resta in decisions).
+export function categorizeCandidate(c) {
+    if (c.kind === "decision" || c.domain === "decisions")
+        return "decisions";
+    const terms = new Set(c.terms.map((t) => t.toLowerCase()));
+    const hay = `${c.subject} ${c.summary}`.toLowerCase();
+    const has = (list) => list.some((t) => terms.has(t) || hay.includes(t));
+    if (FAILURE_DOMAINS.has(c.domain) || has(FAILURE_TERMS))
+        return "failures";
+    if (PATCH_DOMAINS.has(c.domain) || (c.domain === "plan" && has(PATCH_TERMS)) || has(PATCH_TERMS))
+        return "patchplan";
+    if (CODEGRAPH_DOMAINS.has(c.domain) || c.kind === "file" || has(CODEGRAPH_TERMS))
+        return "codegraph";
+    return "evidence";
+}
+// Raggruppa una lista di candidati per categoria dev, preservando l'ordine
+// d'arrivo (gia' ordinati per score a monte). Deterministico.
+export function categorizeCandidates(cands) {
+    const buckets = {
+        decisions: [],
+        codegraph: [],
+        failures: [],
+        patchplan: [],
+        evidence: [],
+    };
+    for (const c of cands)
+        buckets[categorizeCandidate(c)].push(c);
+    return buckets;
+}
+// --- render dei blocchi per zona dev ----------------------------------------
+// Decisioni architetturali: linee compatte ad alta priorita' (vincolano).
+export function renderDecisions(cands) {
+    if (!cands.length)
+        return "";
+    const lines = ["INDICE", "1 = decisioni_attive", "", "DEFINIZIONI"];
+    for (const c of cands)
+        lines.push(`@decisione[${c.id}]: "${oneLine(c.summary || c.subject, 140)}"`);
+    lines.push("", "OUTPUT: le decisioni architetturali attive vincolano ogni modifica.");
+    return lines.join("\n");
+}
+// Code graph caldo: simboli/file/moduli rilevanti come handle (id + soggetto).
+export function renderCodeGraph(cands) {
+    if (!cands.length)
+        return "";
+    const lines = ["INDICE", "1 = simboli_e_file_caldi", "", "DEFINIZIONI"];
+    for (const c of cands) {
+        const detail = oneLine(c.summary || c.subject, 110);
+        lines.push(`@nodo[${c.id}]: ${kindLabel(c.kind)}, "${detail}"`);
+    }
+    lines.push("", "OUTPUT: questi sono i nodi del code graph piu' rilevanti al turno; espandi con recall <id>.");
+    return lines.join("\n");
+}
+// Errori e test recenti: failure citabili col corpo (stacktrace/assert).
+export function renderFailures(cands) {
+    if (!cands.length)
+        return "";
+    const blocks = ["INDICE", "1 = errori_test_recenti", "", "DEFINIZIONI"];
+    for (const c of cands) {
+        const body = c.body ? `, dettaglio="${oneLine(c.body, 280)}"` : "";
+        blocks.push(`@failure[${c.id}]: "${oneLine(c.summary || c.subject, 140)}"${body}`);
+    }
+    blocks.push("", "OUTPUT: risolvi gli errori/test rossi prima di aggiungere nuovo codice.");
+    return blocks.join("\n");
+}
+// Patch plan: passi di modifica pianificati/in corso, in ordine.
+export function renderPatchPlan(cands) {
+    if (!cands.length)
+        return "";
+    const lines = ["INDICE", "1 = passi_patch", "", "DEFINIZIONI"];
+    let i = 1;
+    for (const c of cands) {
+        lines.push(`@passo[${i}]: id=${c.id}, "${oneLine(c.summary || c.subject, 140)}"`);
+        i += 1;
+    }
+    lines.push("", "OUTPUT: applica i passi del patch plan in ordine; ogni passo deve lasciare il codice verde.");
+    return lines.join("\n");
+}
+// Evidence generica: prove citabili col corpo (formato compatibile evidence).
+export function renderEvidence(cands) {
+    if (!cands.length)
+        return "";
+    const blocks = [];
+    for (const c of cands) {
+        blocks.push([
+            `[EVIDENCE:${c.id}]`,
+            `domain=${c.domain}`,
+            `kind=${c.kind}`,
+            `subject=${oneLine(c.subject, 100)}`,
+            `summary="${oneLine(c.summary, 160)}"`,
+            `confidence=${c.trust}`,
+            `supersededBy=${c.supersededBy ?? "null"}`,
+            c.body ? `body="${oneLine(c.body, 360)}"` : "",
+        ]
+            .filter(Boolean)
+            .join("\n"));
+    }
+    return blocks.join("\n\n");
+}
+// Recall handles: handle leggeri (id + summary), richiamabili a richiesta.
+export function renderHandles(cands) {
+    if (!cands.length)
+        return "";
+    const lines = ["INDICE", "1 = handles_richiamabili", "", "DEFINIZIONI"];
+    for (const c of cands)
+        lines.push(`@handle[${c.id}]: kind=${c.kind}, "${oneLine(c.summary || c.subject, 90)}"`);
+    lines.push("", "OUTPUT: usa recall <id> per espandere un handle quando serve il dettaglio.");
+    return lines.join("\n");
+}
+// --- assemblaggio del layout dev --------------------------------------------
+// Assembla il Dev Prompt Pack dalle zone non vuote, nell'ordine dev canonico,
+// con intestazioni. Deterministico. Le zone vuote vengono saltate.
+export function assembleDevLayout(content) {
+    const blocks = [];
+    for (const zone of DEV_ZONE_ORDER) {
+        const text = (content[zone] ?? "").trim();
+        if (!text)
+            continue;
+        blocks.push(`${DEV_ZONE_HEADER[zone]}\n${text}`);
+    }
+    return blocks.join("\n\n");
+}
+// --- helper -----------------------------------------------------------------
+function kindLabel(kind) {
+    switch (kind) {
+        case "file":
+            return "file";
+        case "decision":
+            return "decisione";
+        case "task":
+            return "task";
+        case "room":
+            return "attivita";
+        case "note":
+            return "nota";
+        case "asset":
+            return "asset";
+        case "kingdom":
+            return "lista";
+        default:
+            return "nodo";
+    }
+}
+function oneLine(value, max) {
+    const s = value.replace(/\s+/g, " ").trim().replace(/"/g, "'");
+    return s.length > max ? s.slice(0, max - 1).trimEnd() + "…" : s;
+}
+function esc(value) {
+    return value.replace(/\s+/g, " ").trim().replace(/"/g, "'");
+}

package/dist/vascend/evidence-slots.d.ts

@@ -0,0 +1,14 @@
+import type { ContextCandidate } from "./context-candidate.js";
+export interface EvidenceSlot {
+    readonly id: string;
+    readonly domain: string;
+    readonly type: string;
+    readonly subject: string;
+    readonly summary: string;
+    readonly confidence: string;
+    readonly supersededBy: string | null;
+    readonly body: string;
+}
+export declare function toEvidenceSlot(c: ContextCandidate): EvidenceSlot;
+export declare function renderEvidenceSlot(slot: EvidenceSlot): string;
+export declare function renderEvidenceSlots(candidates: readonly ContextCandidate[]): string;

package/dist/vascend/evidence-slots.js

@@ -0,0 +1,55 @@
+// Evidence Slots (metodo Danilov, Memory OS).
+//
+// Non tutto cio' che viene recuperato deve diventare "contesto" generico:
+// alcune cose vanno marcate come PROVE. Cosi' il modello non "ricorda", ma
+// LEGGE prove citabili e tracciabili (id, dominio, confidenza, supersededBy).
+//
+// Formato del documento talos-context:
+//   [EVIDENCE:E142]
+//   domain=decisions
+//   type=decision.made
+//   subject=crm/ui
+//   summary="..."
+//   confidence=high
+//   supersededBy=null
+//   source=assistant+user
+//
+// Modulo PURO: rende ContextCandidate in slot evidenza, deterministico.
+// Costruisce uno slot evidenza da un candidato. Deterministico.
+export function toEvidenceSlot(c) {
+    return {
+        id: c.id,
+        domain: String(c.domain),
+        type: c.kind,
+        subject: oneLine(c.subject, 100),
+        summary: oneLine(c.summary, 180),
+        confidence: c.trust,
+        supersededBy: c.supersededBy,
+        body: oneLine(c.body, 500),
+    };
+}
+// Rende un singolo slot nel formato testuale [EVIDENCE:id].
+export function renderEvidenceSlot(slot) {
+    return [
+        `[EVIDENCE:${slot.id}]`,
+        `domain=${slot.domain}`,
+        `type=${slot.type}`,
+        `subject=${slot.subject}`,
+        `summary="${slot.summary}"`,
+        `confidence=${slot.confidence}`,
+        `supersededBy=${slot.supersededBy ?? "null"}`,
+        slot.body ? `body="${slot.body}"` : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+// Rende un insieme di candidati come blocco Evidence Slots completo.
+export function renderEvidenceSlots(candidates) {
+    if (!candidates.length)
+        return "";
+    return candidates.map((c) => renderEvidenceSlot(toEvidenceSlot(c))).join("\n\n");
+}
+function oneLine(value, max) {
+    const s = (value ?? "").replace(/\s+/g, " ").trim().replace(/"/g, "'");
+    return s.length > max ? s.slice(0, max - 1).trimEnd() + "…" : s;
+}

package/dist/vascend/expansion-levels.d.ts

@@ -0,0 +1,15 @@
+import { type ContextCapsule, type ExpansionLevel } from "./context-capsule.js";
+export declare function tokensAtLevel(capsule: ContextCapsule, level: ExpansionLevel): number;
+export declare function utilityAtLevel(capsule: ContextCapsule, level: ExpansionLevel): number;
+export interface BestExpansionOptions {
+    readonly tokenBudget?: number;
+    readonly costWeight?: number;
+    readonly staleWeight?: number;
+    readonly maxLevel?: ExpansionLevel;
+}
+export declare function staleRiskAtLevel(capsule: ContextCapsule, level: ExpansionLevel): number;
+export declare function bestExpansion(capsule: ContextCapsule, opts?: BestExpansionOptions): ExpansionLevel;
+export declare function expansionScore(capsule: ContextCapsule, level: ExpansionLevel, opts?: BestExpansionOptions): number;
+export declare function renderCapsule(capsule: ContextCapsule, level: ExpansionLevel): string;
+export declare function renderCapsules(capsules: readonly ContextCapsule[]): string;
+export declare function explainExpansion(capsule: ContextCapsule, opts?: BestExpansionOptions): string;

package/dist/vascend/expansion-levels.js

@@ -0,0 +1,178 @@
+// Expansion Levels R0-R4 (metodo Danilov, Memory OS) -- L2: Packet Algebra.
+//
+// Il salto sopra il tier HIGH/MID/LOW: non si sceglie piu' "corpo si'/handle/escluso",
+// ma QUANTO espandere ogni capsula. Cinque livelli di rate-distortion semantica:
+//
+//   R0 = handle           (memoria fredda: id + come recuperarla)
+//   R1 = summary          (utile ma non critica: 1 riga + metadata)
+//   R2 = summary + reason  (decisioni: cosa + perche')
+//   R3 = evidence         (risposta deve essere grounded: prova citabile)
+//   R4 = body completo    (task rischioso o dettaglio necessario)
+//
+// La scelta del livello e' un'OTTIMIZZAZIONE: per ogni capsula
+//
+//   bestExpansion(capsule) =
+//     argmax_level  utility(level) - tokenCost(level) - staleRisk(level)
+//
+// Questo sostituisce il taglio grezzo clampToBudget con una compressione a
+// livelli semantici (rate-distortion): comprimo finche' non perdo cio' che serve.
+//
+// Modulo PURO e DETERMINISTICO: nessun side-effect, nessuna rete, stima token
+// ~4 char/token coerente col resto del Memory OS.
+import { EXPANSION_LEVELS, EXPANSION_LABEL, isStale, } from "./context-capsule.js";
+// Stima dei token che la capsula occupa AL LIVELLO indicato. Deterministica.
+export function tokensAtLevel(capsule, level) {
+    const text = renderCapsule(capsule, level);
+    return Math.max(1, Math.ceil(text.length / 4));
+}
+// Frazione di utilita' "consegnata" a ciascun livello: piu' espando, piu'
+// dell'utilita' della capsula arriva al modello, con rendimenti decrescenti.
+// R0 da' poco (solo il puntatore), R3/R4 danno quasi tutto. Deterministico.
+const UTILITY_FRACTION = {
+    0: 0.2,
+    1: 0.5,
+    2: 0.7,
+    3: 0.9,
+    4: 1.0,
+};
+// Utilita' consegnata al livello: utilita' della capsula * frazione del livello.
+// Per le capsule SENZA contenuto adatto a un livello (es. nessun reason per R2,
+// nessuna proof per R3) il livello non aggiunge nulla oltre R1.
+export function utilityAtLevel(capsule, level) {
+    let frac = UTILITY_FRACTION[level];
+    if (level >= 2 && !capsule.reason && !capsule.proof && !capsule.body)
+        frac = UTILITY_FRACTION[1];
+    if (level === 3 && !capsule.proof && !capsule.body)
+        frac = Math.min(frac, UTILITY_FRACTION[2]);
+    if (level === 4 && !capsule.body)
+        frac = Math.min(frac, UTILITY_FRACTION[3]);
+    return clamp01(capsule.metrics.utility * frac);
+}
+// Rischio stale al livello: una capsula obsoleta che entra come BODY (R4) e'
+// pericolosa (puo' far credere al modello che sia attuale); come handle (R0)
+// e' innocua. Cresce col livello solo se la capsula e' stale.
+export function staleRiskAtLevel(capsule, level) {
+    if (!isStale(capsule))
+        return 0;
+    // 0 a R0, fino a ~1 a R4: piu' la esponi, piu' rischi.
+    return clamp01(level / 4);
+}
+// Sceglie il livello di espansione ottimale per una capsula:
+//   argmax_level  utility(level) - costWeight*tokenCost(level)/budget - staleWeight*staleRisk(level)
+// Deterministico: a parita' di capsula+opzioni, stesso livello (tie-break: il
+// livello PIU' BASSO a parita' di score, per parsimonia di token).
+export function bestExpansion(capsule, opts = {}) {
+    const budget = opts.tokenBudget && opts.tokenBudget > 0 ? opts.tokenBudget : 2_000;
+    const costWeight = opts.costWeight ?? 1;
+    const staleWeight = opts.staleWeight ?? 1;
+    const maxLevel = opts.maxLevel ?? 4;
+    let bestLevel = 0;
+    let bestScore = -Infinity;
+    for (const level of EXPANSION_LEVELS) {
+        if (level > maxLevel)
+            break;
+        const u = utilityAtLevel(capsule, level);
+        const cost = (costWeight * tokensAtLevel(capsule, level)) / budget;
+        const stale = staleWeight * staleRiskAtLevel(capsule, level);
+        const score = u - cost - stale;
+        // Tie-break parsimonioso: aggiorna solo se STRETTAMENTE migliore, cosi' a
+        // parita' resta il livello piu' basso gia' trovato.
+        if (score > bestScore + 1e-9) {
+            bestScore = score;
+            bestLevel = level;
+        }
+    }
+    return bestLevel;
+}
+// Punteggio della scelta (per diagnostica): l'obiettivo al livello dato.
+export function expansionScore(capsule, level, opts = {}) {
+    const budget = opts.tokenBudget && opts.tokenBudget > 0 ? opts.tokenBudget : 2_000;
+    const costWeight = opts.costWeight ?? 1;
+    const staleWeight = opts.staleWeight ?? 1;
+    return (utilityAtLevel(capsule, level) -
+        (costWeight * tokensAtLevel(capsule, level)) / budget -
+        staleWeight * staleRiskAtLevel(capsule, level));
+}
+// --- rendering per livello --------------------------------------------------
+// Rende una capsula nel testo del livello richiesto. Deterministico.
+//   R0 -> riga handle con istruzione di recall
+//   R1 -> blocco summary + metadata
+//   R2 -> R1 + reason (perche')
+//   R3 -> evidence slot citabile (proof)
+//   R4 -> evidence slot + body completo
+export function renderCapsule(capsule, level) {
+    const h = capsule.header;
+    switch (level) {
+        case 0:
+            return `@handle[${h.id}]: ${h.type}/${h.domain} -> recall:${capsule.recall.id ?? h.id}${capsule.recall.query ? ` (${capsule.recall.query})` : ""}`;
+        case 1:
+            return [
+                `[CAPSULE:${h.id}] R1`,
+                `domain=${h.domain} type=${h.type} status=${h.status} confidence=${h.confidence}`,
+                `summary="${capsule.summary}"`,
+            ].join("\n");
+        case 2:
+            return [
+                `[CAPSULE:${h.id}] R2`,
+                `domain=${h.domain} type=${h.type} status=${h.status} confidence=${h.confidence}`,
+                `summary="${capsule.summary}"`,
+                capsule.reason ? `reason="${capsule.reason}"` : "",
+            ]
+                .filter(Boolean)
+                .join("\n");
+        case 3:
+            return [
+                `[EVIDENCE:${h.id}]`,
+                `domain=${h.domain}`,
+                `type=${h.type}`,
+                `summary="${capsule.summary}"`,
+                `confidence=${h.confidence}`,
+                `supersededBy=${capsule.lineage.supersededBy ?? "null"}`,
+                capsule.proof ? `proof="${capsule.proof}"` : capsule.reason ? `reason="${capsule.reason}"` : "",
+            ]
+                .filter(Boolean)
+                .join("\n");
+        case 4:
+        default:
+            return [
+                `[EVIDENCE:${h.id}]`,
+                `domain=${h.domain}`,
+                `type=${h.type}`,
+                `summary="${capsule.summary}"`,
+                `confidence=${h.confidence}`,
+                `supersededBy=${capsule.lineage.supersededBy ?? "null"}`,
+                capsule.body ? `body="${oneLine(capsule.body, 600)}"` : capsule.proof ? `proof="${capsule.proof}"` : "",
+            ]
+                .filter(Boolean)
+                .join("\n");
+    }
+}
+// Rende un insieme di capsule, ognuna al SUO expansionLevel corrente. Le capsule
+// allo stesso livello sono separate da riga vuota; deterministico nell'ordine.
+export function renderCapsules(capsules) {
+    return capsules
+        .map((c) => renderCapsule(c, c.expansionLevel))
+        .filter(Boolean)
+        .join("\n\n");
+}
+// Diagnostica: riga compatta livello scelto + motivazione (utility/cost/stale).
+export function explainExpansion(capsule, opts = {}) {
+    const level = bestExpansion(capsule, opts);
+    return `@expansion[${capsule.header.id}]: R${level} (${EXPANSION_LABEL[level]}) util=${round(utilityAtLevel(capsule, level))} cost=${tokensAtLevel(capsule, level)}tok stale=${round(staleRiskAtLevel(capsule, level))}`;
+}
+function oneLine(value, max) {
+    const s = (value ?? "").replace(/\s+/g, " ").trim().replace(/"/g, "'");
+    return s.length > max ? s.slice(0, max - 1).trimEnd() + "\u2026" : s;
+}
+function clamp01(v) {
+    if (Number.isNaN(v))
+        return 0;
+    if (v < 0)
+        return 0;
+    if (v > 1)
+        return 1;
+    return v;
+}
+function round(v) {
+    return Math.round(v * 1000) / 1000;
+}

package/dist/vascend/file-lock.d.ts

@@ -0,0 +1,7 @@
+export interface FileLockOptions {
+    readonly staleMs?: number;
+    readonly timeoutMs?: number;
+    readonly retryMs?: number;
+}
+export declare function acquireLockSync(target: string, opts?: FileLockOptions): () => void;
+export declare function withLockSync<T>(target: string, fn: () => T, opts?: FileLockOptions): T;

package/dist/vascend/file-lock.js

@@ -0,0 +1,95 @@
+import { mkdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+const DEFAULT_STALE_MS = 10_000;
+const DEFAULT_TIMEOUT_MS = 5_000;
+const DEFAULT_RETRY_MS = 15;
+function lockDirFor(target) {
+    return `${target}.lock`;
+}
+// Attesa sincrona breve (busy-wait) senza dipendenze: usa Atomics.wait su un
+// buffer condiviso fittizio (sleep reale del thread), con fallback a spin.
+function sleepSync(ms) {
+    if (ms <= 0)
+        return;
+    try {
+        const shared = new Int32Array(new SharedArrayBuffer(4));
+        Atomics.wait(shared, 0, 0, ms);
+    }
+    catch {
+        const end = Date.now() + ms;
+        while (Date.now() < end) {
+            /* spin */
+        }
+    }
+}
+function isStale(lockDir, staleMs) {
+    try {
+        const st = statSync(lockDir);
+        return Date.now() - st.mtimeMs > staleMs;
+    }
+    catch {
+        // Non esiste piu': non e' stale, e' libero.
+        return false;
+    }
+}
+// Acquisisce il lock per `target` (path del file da proteggere). Ritorna una
+// funzione di rilascio. Lancia se non riesce entro il timeout.
+export function acquireLockSync(target, opts = {}) {
+    const staleMs = opts.staleMs ?? DEFAULT_STALE_MS;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const retryMs = opts.retryMs ?? DEFAULT_RETRY_MS;
+    const lockDir = lockDirFor(target);
+    mkdirSync(dirname(target), { recursive: true });
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            // mkdir senza recursive fallisce se la dir esiste gia': e' il nostro CAS.
+            mkdirSync(lockDir);
+            // Marca chi/quando per la diagnostica dello stale.
+            try {
+                writeFileSync(`${lockDir}/owner`, `${process.pid}:${Date.now()}`, "utf8");
+            }
+            catch {
+                /* la marcatura e' best-effort */
+            }
+            let released = false;
+            return () => {
+                if (released)
+                    return;
+                released = true;
+                try {
+                    rmSync(lockDir, { recursive: true, force: true });
+                }
+                catch {
+                    /* gia' rimosso */
+                }
+            };
+        }
+        catch {
+            // Lock occupato: se e' stale, forzalo; altrimenti aspetta.
+            if (isStale(lockDir, staleMs)) {
+                try {
+                    rmSync(lockDir, { recursive: true, force: true });
+                }
+                catch {
+                    /* qualcun altro l'ha appena tolto */
+                }
+                continue;
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`file-lock: timeout acquisendo ${lockDir} (${timeoutMs}ms)`);
+            }
+            sleepSync(retryMs);
+        }
+    }
+}
+// Esegue `fn` tenendo il lock su `target`, garantendone il rilascio.
+export function withLockSync(target, fn, opts) {
+    const release = acquireLockSync(target, opts);
+    try {
+        return fn();
+    }
+    finally {
+        release();
+    }
+}

package/dist/vascend/granular-kingdom.d.ts

@@ -0,0 +1,25 @@
+import type { Harness } from "../core/bootstrap.js";
+import type { AgentEvent, ToolContext } from "../core/types.js";
+import { type FileCoordinationContext } from "../core/file-coordination.js";
+import { type TaskUnit, type TaskRunner, type GranularLaunchReport } from "./granular-launcher.js";
+export interface GranularKingdomOptions {
+    readonly harness: Harness;
+    readonly kingdomId: string;
+    readonly castleSlug: string;
+    readonly units: readonly TaskUnit[];
+    readonly signal: AbortSignal;
+    readonly confirm: (action: string, detail: string) => Promise<boolean>;
+    readonly ask?: ToolContext["ask"];
+    readonly fileCoordination?: FileCoordinationContext;
+    readonly concurrency?: number;
+    readonly onEvent?: (id: string, event: AgentEvent) => void;
+    readonly onNotice?: (text: string) => void;
+    readonly cwd?: string;
+    readonly isolated?: boolean;
+    readonly planStoreId?: string;
+    readonly markCastle?: string;
+    readonly depth?: number;
+    readonly maxDepth?: number;
+}
+export declare function makeAgentUnitRunner(opts: GranularKingdomOptions): TaskRunner;
+export declare function launchGranularKingdom(opts: GranularKingdomOptions): Promise<GranularLaunchReport>;