@vascend/talos 0.1.0

package/dist/vascend/architecture-map.js

@@ -0,0 +1,424 @@
+// Mappa architetturale del workspace (funzionalita' di architettura Vascend).
+//
+// Costruisce una vista MODULO-centrica del progetto: raggruppa i file in moduli
+// per directory, estrae le dipendenze interne (import relativi risolti al
+// modulo di destinazione), rileva i cicli fra moduli (SCC), individua entry
+// point, hotspot (file piu' grandi) e dipendenze esterne aggregate.
+//
+// Due strati:
+//   - buildArchitectureMap: PURO, input {path,source}[] -> ArchitectureMap
+//     (testabile in memoria, nessun side-effect);
+//   - scanArchitectureMap: orchestrazione su disco con limiti duri (max file,
+//     max bytes) e ignore-set condiviso con glob/grep.
+//
+// Il render (renderArchitectureMap) produce markdown compatto pensato per tre
+// consumatori: il tool `architecture_map` (chat Horizon in vascend-terminal),
+// il comando TUI `/arch` e la modalita' print.
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { parseSource } from "./code-parser.js";
+// --- classificazione --------------------------------------------------------
+const CODE_EXT_RE = /\.(?:ts|tsx|js|jsx|mjs|cjs)$/i;
+const PY_EXT_RE = /\.py$/i;
+export function isArchSourceFile(path) {
+    return CODE_EXT_RE.test(path) || PY_EXT_RE.test(path);
+}
+// Modulo di appartenenza di un file: i primi `depth` segmenti della directory.
+// File alla radice -> "(root)".
+export function moduleIdOf(path, depth) {
+    const parts = path.split("/");
+    parts.pop(); // via il nome file
+    if (!parts.length)
+        return "(root)";
+    return parts.slice(0, Math.max(1, depth)).join("/");
+}
+// Nome pacchetto di un import esterno: "@scope/pkg/sub" -> "@scope/pkg",
+// "react/jsx-runtime" -> "react", "node:fs/promises" -> "node:fs".
+export function externalPackageName(module) {
+    const m = module.trim();
+    if (!m)
+        return "";
+    if (m.startsWith("node:"))
+        return m.split("/")[0] ?? m;
+    const parts = m.split("/");
+    if (m.startsWith("@") && parts.length >= 2)
+        return `${parts[0]}/${parts[1]}`;
+    return parts[0] ?? m;
+}
+// --- risoluzione import relativi --------------------------------------------
+// Normalizza un path con "." e ".." senza toccare il filesystem.
+export function normalizeRelPath(path) {
+    const out = [];
+    for (const part of path.split("/")) {
+        if (!part || part === ".")
+            continue;
+        if (part === "..") {
+            out.pop();
+            continue;
+        }
+        out.push(part);
+    }
+    return out.join("/");
+}
+const RESOLVE_SUFFIXES = [
+    "", ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".d.ts",
+    "/index.ts", "/index.tsx", "/index.js", "/index.jsx",
+];
+// Risolve un import relativo al file di destinazione fra quelli noti.
+// Gestisce la convenzione node16 di questo repo (import "./x.js" -> "x.ts").
+export function resolveRelativeImport(fromFile, spec, known) {
+    const dir = fromFile.split("/").slice(0, -1).join("/");
+    const base = normalizeRelPath(dir ? `${dir}/${spec}` : spec);
+    if (!base)
+        return null;
+    // Swap estensione .js -> sorgente TS (layout tsc node16).
+    const candidates = [];
+    const jsSwap = base.replace(/\.(js|jsx|mjs|cjs)$/i, "");
+    for (const suffix of RESOLVE_SUFFIXES) {
+        candidates.push(base + suffix);
+        if (jsSwap !== base)
+            candidates.push(jsSwap + suffix);
+    }
+    for (const candidate of candidates) {
+        if (known.has(candidate))
+            return candidate;
+    }
+    return null;
+}
+// --- import Python (best effort) ---------------------------------------------
+// Estrae i moduli importati da un sorgente Python: `import a.b`, `from a import b`,
+// `from . import x` / `from .mod import y` (relativi -> stesso package).
+export function parsePythonImports(source) {
+    const externals = [];
+    let relative = false;
+    for (const rawLine of source.split("\n")) {
+        const line = rawLine.trim();
+        let m = /^import\s+([A-Za-z_][\w.]*)/.exec(line);
+        if (m) {
+            externals.push((m[1] ?? "").split(".")[0] ?? "");
+            continue;
+        }
+        m = /^from\s+(\.*)([A-Za-z_][\w.]*)?\s+import\s+/.exec(line);
+        if (m) {
+            if (m[1])
+                relative = true;
+            else if (m[2])
+                externals.push((m[2] ?? "").split(".")[0] ?? "");
+        }
+    }
+    return { externals: externals.filter(Boolean), relative };
+}
+// --- cicli (SCC, Tarjan iterativo) -------------------------------------------
+// Componenti fortemente connesse del grafo dei moduli; ritorna solo quelle con
+// almeno 2 nodi (i cicli architetturali veri).
+export function findModuleCycles(nodes, edges) {
+    let counter = 0;
+    const index = new Map();
+    const low = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const sccs = [];
+    for (const start of nodes) {
+        if (index.has(start))
+            continue;
+        const frames = [];
+        const open = (node) => {
+            index.set(node, counter);
+            low.set(node, counter);
+            counter += 1;
+            stack.push(node);
+            onStack.add(node);
+            const targets = edges.get(node) ?? new Set();
+            frames.push({ node, iter: targets[Symbol.iterator]() });
+        };
+        open(start);
+        while (frames.length) {
+            const frame = frames[frames.length - 1];
+            const next = frame.iter.next();
+            if (!next.done) {
+                const target = next.value;
+                if (!index.has(target))
+                    open(target);
+                else if (onStack.has(target)) {
+                    low.set(frame.node, Math.min(low.get(frame.node), index.get(target)));
+                }
+                continue;
+            }
+            frames.pop();
+            const parent = frames[frames.length - 1];
+            if (parent)
+                low.set(parent.node, Math.min(low.get(parent.node), low.get(frame.node)));
+            if (low.get(frame.node) === index.get(frame.node)) {
+                const scc = [];
+                for (;;) {
+                    const popped = stack.pop();
+                    onStack.delete(popped);
+                    scc.push(popped);
+                    if (popped === frame.node)
+                        break;
+                }
+                if (scc.length >= 2)
+                    sccs.push(scc.sort());
+            }
+        }
+    }
+    return sccs.sort((a, b) => (a[0] ?? "").localeCompare(b[0] ?? ""));
+}
+// --- entry point --------------------------------------------------------------
+const CONVENTIONAL_ENTRIES = [
+    "src/index.ts", "src/index.tsx", "src/index.js", "index.ts", "index.js",
+    "src/main.ts", "src/main.js", "main.py", "app.py", "src/cli.ts",
+];
+function packageEntryPoints(pkg, known) {
+    if (!pkg)
+        return [];
+    const out = [];
+    const norm = (value) => normalizeRelPath(String(value ?? "").replace(/^\.\//, ""));
+    const push = (file, reason) => {
+        if (file && known.has(file) && !out.some((e) => e.file === file))
+            out.push({ file, reason });
+    };
+    push(norm(pkg["main"]), "package.json main");
+    const bin = pkg["bin"];
+    if (typeof bin === "string")
+        push(norm(bin), "package.json bin");
+    else if (bin && typeof bin === "object") {
+        for (const [name, value] of Object.entries(bin)) {
+            push(norm(value), `package.json bin "${name}"`);
+        }
+    }
+    const exportsField = pkg["exports"];
+    if (typeof exportsField === "string")
+        push(norm(exportsField), "package.json exports");
+    else if (exportsField && typeof exportsField === "object") {
+        const dot = exportsField["."];
+        if (typeof dot === "string")
+            push(norm(dot), "package.json exports \".\"");
+    }
+    return out;
+}
+// --- build (puro) --------------------------------------------------------------
+export function buildArchitectureMap(files, options = {}) {
+    const depth = Math.max(1, options.moduleDepth ?? 2);
+    const top = Math.max(3, options.top ?? 10);
+    const known = new Set(files.map((f) => f.path));
+    const modules = new Map();
+    const edgeCounts = new Map(); // "fromto" -> count
+    const externals = new Map();
+    const hotspots = [];
+    let totalLoc = 0;
+    const modOf = (path) => moduleIdOf(path, depth);
+    const bump = (path) => {
+        const id = modOf(path);
+        let acc = modules.get(id);
+        if (!acc) {
+            acc = { files: 0, loc: 0, exports: 0, testFiles: 0 };
+            modules.set(id, acc);
+        }
+        return acc;
+    };
+    for (const file of files) {
+        if (!isArchSourceFile(file.path))
+            continue;
+        const loc = file.source.length ? file.source.split("\n").length : 0;
+        totalLoc += loc;
+        const acc = bump(file.path);
+        acc.files += 1;
+        acc.loc += loc;
+        hotspots.push({ file: file.path, loc });
+        if (PY_EXT_RE.test(file.path)) {
+            const py = parsePythonImports(file.source);
+            if (/(^|\/)(test|tests)\//.test(file.path) || /_test\.py$/.test(file.path) || /(^|\/)test_[^/]*\.py$/.test(file.path)) {
+                acc.testFiles += 1;
+            }
+            for (const ext of py.externals) {
+                externals.set(ext, (externals.get(ext) ?? 0) + 1);
+            }
+            continue;
+        }
+        const parsed = parseSource(file.path, file.source);
+        if (parsed.isTest)
+            acc.testFiles += 1;
+        acc.exports += parsed.symbols.filter((s) => s.exported).length;
+        for (const imp of parsed.imports) {
+            if (imp.external) {
+                const name = externalPackageName(imp.module);
+                if (name)
+                    externals.set(name, (externals.get(name) ?? 0) + 1);
+                continue;
+            }
+            const target = resolveRelativeImport(file.path, imp.module, known);
+            if (!target)
+                continue;
+            const fromMod = modOf(file.path);
+            const toMod = modOf(target);
+            if (fromMod === toMod)
+                continue;
+            const key = `${fromMod}${toMod}`;
+            edgeCounts.set(key, (edgeCounts.get(key) ?? 0) + 1);
+        }
+    }
+    const dependencies = [...edgeCounts.entries()]
+        .map(([key, count]) => {
+        const [from = "", to = ""] = key.split("");
+        return { from, to, count };
+    })
+        .sort((a, b) => b.count - a.count || a.from.localeCompare(b.from));
+    const adjacency = new Map();
+    for (const dep of dependencies) {
+        let set = adjacency.get(dep.from);
+        if (!set) {
+            set = new Set();
+            adjacency.set(dep.from, set);
+        }
+        set.add(dep.to);
+    }
+    const cycles = findModuleCycles([...modules.keys()], adjacency);
+    const entryPoints = packageEntryPoints(options.packageJson, known);
+    for (const conventional of CONVENTIONAL_ENTRIES) {
+        if (known.has(conventional) && !entryPoints.some((e) => e.file === conventional)) {
+            entryPoints.push({ file: conventional, reason: "convenzione" });
+        }
+    }
+    const moduleStats = [...modules.entries()]
+        .map(([id, acc]) => ({ id, ...acc }))
+        .sort((a, b) => b.loc - a.loc || a.id.localeCompare(b.id));
+    return {
+        rootName: options.rootName ?? "",
+        files: moduleStats.reduce((sum, m) => sum + m.files, 0),
+        loc: totalLoc,
+        modules: moduleStats,
+        dependencies,
+        cycles,
+        entryPoints,
+        hotspots: hotspots.sort((a, b) => b.loc - a.loc).slice(0, top),
+        externals: [...externals.entries()]
+            .map(([module, count]) => ({ module, count }))
+            .sort((a, b) => b.count - a.count || a.module.localeCompare(b.module))
+            .slice(0, top),
+        truncated: options.truncated === true,
+    };
+}
+// --- render -------------------------------------------------------------------
+export function renderArchitectureMap(map, options = {}) {
+    const maxModules = Math.max(5, options.maxModules ?? 24);
+    const lines = [];
+    const title = map.rootName ? `Architettura — ${map.rootName}` : "Architettura";
+    lines.push(`# ${title}`);
+    lines.push(`${map.files} file sorgente · ${map.loc.toLocaleString("it-IT")} LOC · ` +
+        `${map.modules.length} moduli · ${map.dependencies.length} dipendenze interne` +
+        (map.truncated ? " · SCAN PARZIALE (limite file raggiunto)" : ""));
+    lines.push("", "## Moduli (per LOC)");
+    const deps = new Map();
+    for (const d of map.dependencies) {
+        const list = deps.get(d.from) ?? [];
+        list.push(d.to);
+        deps.set(d.from, list);
+    }
+    for (const mod of map.modules.slice(0, maxModules)) {
+        const to = (deps.get(mod.id) ?? []).slice(0, 6);
+        lines.push(`- ${mod.id}: ${mod.files} file, ${mod.loc} LOC, ${mod.exports} export` +
+            (mod.testFiles ? `, ${mod.testFiles} test` : "") +
+            (to.length ? ` -> ${to.join(", ")}` : ""));
+    }
+    if (map.modules.length > maxModules)
+        lines.push(`- … altri ${map.modules.length - maxModules} moduli`);
+    lines.push("", "## Cicli fra moduli");
+    if (!map.cycles.length)
+        lines.push("- nessun ciclo rilevato");
+    for (const cycle of map.cycles)
+        lines.push(`- CICLO: ${cycle.join(" <-> ")}`);
+    lines.push("", "## Entry point");
+    if (!map.entryPoints.length)
+        lines.push("- nessuno riconosciuto");
+    for (const entry of map.entryPoints)
+        lines.push(`- ${entry.file} (${entry.reason})`);
+    lines.push("", "## Hotspot (file piu' grandi)");
+    for (const hot of map.hotspots)
+        lines.push(`- ${hot.file} (${hot.loc} righe)`);
+    if (map.externals.length) {
+        lines.push("", "## Dipendenze esterne (per numero di import)");
+        for (const ext of map.externals)
+            lines.push(`- ${ext.module} (${ext.count})`);
+    }
+    return lines.join("\n");
+}
+// --- scan su disco --------------------------------------------------------------
+// Stesso ignore-set di glob/grep (builtin), duplicato qui per non creare un
+// import circolare tools -> vascend -> tools.
+const SCAN_IGNORE = new Set([
+    "node_modules", ".git", "dist", "build", ".next", ".turbo", ".cache",
+    "coverage", ".venv", "venv", "__pycache__", "target", ".idea", ".vscode",
+    "output", "tmp",
+]);
+// Scansiona il workspace e costruisce la mappa. Limiti duri: file oltre il cap
+// -> truncated=true; file oltre maxFileBytes ignorati (bundle/generati).
+export function scanArchitectureMap(root, options = {}) {
+    const maxFiles = Math.max(10, options.maxFiles ?? 4000);
+    const maxBytes = Math.max(4096, options.maxFileBytes ?? 1024 * 1024);
+    const files = [];
+    let truncated = false;
+    const stack = [root];
+    while (stack.length) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            if (files.length >= maxFiles) {
+                truncated = true;
+                break;
+            }
+            const full = join(dir, name);
+            let stat;
+            try {
+                stat = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (stat.isDirectory()) {
+                if (SCAN_IGNORE.has(name) || name.startsWith("."))
+                    continue;
+                stack.push(full);
+                continue;
+            }
+            if (!stat.isFile() || !isArchSourceFile(name) || stat.size > maxBytes)
+                continue;
+            let source;
+            try {
+                source = readFileSync(full, "utf8");
+            }
+            catch {
+                continue;
+            }
+            files.push({ path: relForward(root, full), source });
+        }
+        if (truncated)
+            break;
+    }
+    let packageJson = null;
+    try {
+        const parsed = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            packageJson = parsed;
+        }
+    }
+    catch { /* package.json assente o invalido: gli entry point restano convenzionali */ }
+    const rootName = root.replace(/[\\/]+$/, "").split(/[\\/]/).pop() ?? "";
+    return buildArchitectureMap(files, {
+        rootName,
+        truncated,
+        ...(options.moduleDepth !== undefined ? { moduleDepth: options.moduleDepth } : {}),
+        ...(options.top !== undefined ? { top: options.top } : {}),
+        packageJson,
+    });
+}
+function relForward(root, abs) {
+    const rel = relative(root, abs);
+    return (rel || abs).split(/[\\/]/).join("/");
+}

package/dist/vascend/attention-layout.d.ts

@@ -0,0 +1,19 @@
+import type { ContextZone } from "./budget-allocator.js";
+export type ZoneContent = Partial<Record<ContextZone, string>>;
+export declare const ZONE_ORDER: readonly ContextZone[];
+export declare function layoutOverheadTokens(zones: readonly ContextZone[]): number;
+export interface MissionAnchorInput {
+    readonly goal: string;
+    readonly constraints?: readonly string[];
+    readonly success?: string;
+}
+export declare function buildMissionAnchor(input: MissionAnchorInput, maxTokens?: number): string;
+export interface TailAnchorInput {
+    readonly goal: string;
+    readonly constraints?: readonly string[];
+    readonly activeDecisions?: readonly string[];
+    readonly nextAction?: string;
+    readonly recallPolicy?: boolean;
+}
+export declare function buildTailAnchor(input: TailAnchorInput, maxTokens?: number): string;
+export declare function assembleLayout(content: ZoneContent): string;

package/dist/vascend/attention-layout.js

@@ -0,0 +1,141 @@
+// Attention-Safe Layout (metodo Danilov, Memory OS).
+//
+// La context window non e' uno spazio uniforme: l'attenzione del modello
+// degrada nel mezzo ("lost in the middle"). Questo modulo dispone le ZONE del
+// prompt nell'ordine 1-9 del documento talos-context, mettendo le ancore
+// fondamentali in TESTA (mission anchor) e in CODA (tail anchor) cosi' che le
+// cose critiche siano riprese prima della generazione.
+//
+//   1. System invariants     (testa, non comprimibile)
+//   2. Mission Anchor        (obiettivo, vincoli, definizione di successo)
+//   3. Vision + Piano attivo
+//   4. Memory Packet L0
+//   5. Evidence Slots
+//   6. Recall Handles
+//   7. Tool State
+//   8. User Turn
+//   9. Tail Anchor           (coda, riassunto operativo finale)
+//
+// Modulo PURO: assembla stringhe gia' pronte in un ordine fisso e produce il
+// testo finale del Prompt Pack.
+import { estimateTokens } from "./budget-allocator.js";
+// Ordine canonico delle zone (1-9). "user" e "tail" vanno in fondo per
+// combattere il lost-in-the-middle.
+export const ZONE_ORDER = [
+    "system",
+    "mission",
+    "vision",
+    "memory",
+    "evidence",
+    "recall",
+    "tool",
+    "user",
+    "tail",
+];
+// Intestazioni leggibili per zona (commenti del pack, in notazione Danilov).
+const ZONE_HEADER = {
+    system: "[CTX:SYSTEM_INVARIANTS]",
+    mission: "[CTX:MISSION_ANCHOR]",
+    vision: "[CTX:VISION_E_PIANO]",
+    memory: "[CTX:MEMORY_PACKET]",
+    evidence: "[CTX:EVIDENCE_SLOTS]",
+    recall: "[CTX:RECALL_HANDLES]",
+    tool: "[CTX:TOOL_STATE]",
+    user: "[CTX:USER_TURN]",
+    tail: "[CTX:TAIL_ANCHOR]",
+};
+// Riserva intestazioni e separatori PRIMA di assegnare i budget ai contenuti.
+// Un clamp dopo il layout puo' cancellare la tail o spezzare l'ultima prova.
+export function layoutOverheadTokens(zones) {
+    return zones.reduce((sum, zone) => sum + estimateTokens(`${ZONE_HEADER[zone]}\n\n\n`), 0);
+}
+export function buildMissionAnchor(input, maxTokens) {
+    if (maxTokens !== undefined)
+        return boundedAnchor([
+            ...(input.constraints?.length ? [constraintField("@vincoli[attivi]", input.constraints)] : []),
+            ...(input.success ? [{ label: "@successo[definizione]", value: input.success }] : []),
+            { label: "@obiettivo[corrente]", value: input.goal, shorten: true },
+        ], maxTokens);
+    const lines = ["INDICE", "1 = obiettivo", "2 = vincoli", "3 = successo", "", "DEFINIZIONI"];
+    lines.push(`@obiettivo[corrente]: "${esc(input.goal)}"`);
+    if (input.constraints?.length) {
+        lines.push(`@vincoli[attivi]: ${input.constraints.map((c) => `"${esc(c)}"`).join(", ")}`);
+    }
+    if (input.success)
+        lines.push(`@successo[definizione]: "${esc(input.success)}"`);
+    lines.push("", "OUTPUT: tieni questo obiettivo come bussola del turno.");
+    return lines.join("\n");
+}
+export function buildTailAnchor(input, maxTokens) {
+    if (maxTokens !== undefined)
+        return boundedAnchor([
+            ...(input.constraints?.length ? [constraintField("@vincoli[ricorda]", input.constraints)] : []),
+            ...(input.nextAction ? [{ label: "@azione[adesso]", value: input.nextAction, shorten: true }] : []),
+            { label: "@obiettivo[ora]", value: input.goal, shorten: true },
+            ...(input.activeDecisions?.length ? [{ label: "@decisioni[attive]", value: input.activeDecisions.join("; ") }] : []),
+            ...(input.recallPolicy ? [{ label: "@recall[regola]", value: "Se mancano prove sul passato, usa recall." }] : []),
+        ], maxTokens);
+    const lines = ["INDICE", "1 = obiettivo", "2 = vincoli", "3 = decisioni", "4 = azione", "", "DEFINIZIONI"];
+    lines.push(`@obiettivo[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.recallPolicy) {
+        lines.push("@recall[regola]: se la risposta dipende dal passato e manca tra le prove, usa recall, NON indovinare");
+    }
+    lines.push("", "OUTPUT: agisci ORA su @azione restando dentro @vincoli e @decisioni.");
+    return lines.join("\n");
+}
+// Assembla il Prompt Pack finale dalle zone non vuote, nell'ordine canonico,
+// con intestazioni. Deterministico.
+export function assembleLayout(content) {
+    const blocks = [];
+    for (const zone of ZONE_ORDER) {
+        const text = (content[zone] ?? "").trim();
+        if (!text)
+            continue;
+        blocks.push(`${ZONE_HEADER[zone]}\n${text}`);
+    }
+    return blocks.join("\n\n");
+}
+function esc(value) {
+    return value.replace(/\s+/g, " ").trim().replace(/"/g, "'");
+}
+function constraintField(label, constraints) {
+    return {
+        label, value: constraints.join("; "),
+        omission: "Vincoli omessi per budget: recuperarli prima di agire.",
+    };
+}
+// In un'ancora piccola il preambolo INDICE consumava i token destinati ai
+// vincoli e all'azione. Assegna lo spazio ai campi operativi prima del goal,
+// che puo' essere molto lungo. I vincoli entrano interi o con omissione
+// esplicita: troncando una condizione si potrebbe cambiarne il significato.
+function boundedAnchor(fields, maxTokens) {
+    let remaining = Math.max(0, Math.floor(maxTokens)) * 4;
+    const lines = [];
+    for (const field of fields) {
+        const prefix = `${field.label}: "`;
+        const overhead = prefix.length + 1 + (lines.length ? 1 : 0);
+        const available = remaining - overhead;
+        if (available <= 0)
+            continue;
+        let value = esc(field.value);
+        if (value.length > available) {
+            if (field.shorten && available >= 20)
+                value = value.slice(0, available - 1).trimEnd() + "…";
+            else if (field.omission && field.omission.length <= available)
+                value = field.omission;
+            else
+                continue;
+        }
+        lines.push(`${prefix}${value}"`);
+        remaining -= overhead + value.length;
+    }
+    return lines.join("\n");
+}

package/dist/vascend/budget-allocator.d.ts

@@ -0,0 +1,31 @@
+export type ContextZone = "system" | "mission" | "vision" | "memory" | "evidence" | "recall" | "tool" | "user" | "tail";
+export interface BudgetPolicy {
+    readonly system: number;
+    readonly mission: number;
+    readonly vision: number;
+    readonly memory: number;
+    readonly evidence: number;
+    readonly recall: number;
+    readonly tool: number;
+    readonly tail: number;
+}
+export declare const DEFAULT_POLICY: BudgetPolicy;
+export type BudgetAllocation = Readonly<Record<ContextZone, number>>;
+export interface AllocateInput {
+    readonly totalTokens: number;
+    readonly policy?: BudgetPolicy;
+    readonly userTokens?: number;
+}
+export declare function allocateBudget(input: AllocateInput): BudgetAllocation;
+export declare function estimateTokens(text: string): number;
+export declare function clampToBudget(text: string, maxTokens: number): string;
+export interface BudgetItem<T> {
+    readonly ref: T;
+    readonly tokens: number;
+    readonly priority?: number;
+}
+export declare function packToBudget<T>(items: readonly BudgetItem<T>[], maxTokens: number): {
+    readonly included: readonly T[];
+    readonly excluded: readonly T[];
+    readonly usedTokens: number;
+};