@vascend/talos 0.1.0

package/dist/vascend/context-snapshot.js

@@ -0,0 +1,135 @@
+import { createHash } from "node:crypto";
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { collectCandidates } from "./candidate-collector.js";
+import { buildMemoryPacket, clampMemoryPacket } from "./memory-packet.js";
+import { retrieve } from "./context-retriever.js";
+import { ContextSearchIndex } from "./context-search-index.js";
+import { projectMemoryScopes, clearContextScopeIndexes } from "./context-scope-index.js";
+const STORE_SUFFIXES = [".memory.events.jsonl", ".rooms.jsonl", ".decisions.jsonl", ".contracts.jsonl", ".castle.json", ".vision.json"];
+const FABRIC_DIR = "context-fabric";
+const MAX_CACHED_SCOPES = 8;
+const cache = new Map();
+/** Legacy callers can inspect the entire directory; runtime signatures use exact dependencies. */
+export function storeSignature(sessionDir, scopes) {
+    if (!scopes)
+        return legacyStoreSignature(sessionDir);
+    try {
+        statSync(sessionDir);
+    }
+    catch {
+        return "";
+    }
+    const hash = createHash("sha256");
+    for (const scope of [...new Set(scopes)].sort())
+        for (const suffix of STORE_SUFFIXES) {
+            const name = scope + suffix;
+            try {
+                const stat = statSync(join(sessionDir, name));
+                hash.update(name + ":" + stat.size + ":" + stat.mtimeMs + ":" + stat.ctimeMs + "\n");
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    return "";
+                hash.update(name + ":missing\n");
+            }
+        }
+    return hash.digest("hex");
+}
+function legacyStoreSignature(sessionDir) {
+    let names;
+    try {
+        names = readdirSync(sessionDir);
+    }
+    catch {
+        return "";
+    }
+    const hash = createHash("sha1");
+    let counted = 0;
+    for (const name of names.sort()) {
+        if (!STORE_SUFFIXES.some((suffix) => name.endsWith(suffix)))
+            continue;
+        try {
+            const st = statSync(join(sessionDir, name));
+            hash.update(`${name}:${st.size}:${st.mtimeMs}\n`);
+            counted += 1;
+        }
+        catch {
+            // Un file svanito fra readdir e stat e' esso stesso un cambiamento:
+            // marcalo, cosi' la firma non coincide con quella precedente.
+            hash.update(`${name}:gone\n`);
+        }
+    }
+    try {
+        const fabricDir = join(sessionDir, FABRIC_DIR);
+        const frames = readdirSync(fabricDir).filter((name) => name.endsWith(".json")).sort();
+        hash.update(`fabric-count:${frames.length}\n`);
+        for (const name of frames) {
+            const st = statSync(join(fabricDir, name));
+            hash.update(`fabric:${name}:${st.size}:${st.mtimeMs}\n`);
+        }
+    }
+    catch {
+        hash.update("fabric:none\n");
+    }
+    return `${counted}-${hash.digest("hex").slice(0, 16)}`;
+}
+export function loadContextStoreSnapshot(input) {
+    const indexed = input.indexed ?? process.env["TALOS_CONTEXT_INDEX"] !== "0";
+    const key = JSON.stringify([input.sessionDir, input.scopeId, input.projectKey, input.planScopeId, indexed]);
+    const projectScopes = indexed
+        ? (input.projectKey ? projectMemoryScopes(input.sessionDir, input.projectKey) : []).filter((scope) => scope !== input.scopeId).sort()
+        : undefined;
+    const scopes = indexed ? [input.scopeId, ...(projectScopes ?? []), ...(input.planScopeId ? [input.planScopeId] : [])] : undefined;
+    const signature = storeSignature(input.sessionDir, scopes);
+    const previous = cache.get(key);
+    if (signature && previous?.signature === signature) {
+        cache.delete(key);
+        cache.set(key, previous);
+        return previous;
+    }
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const before = storeSignature(input.sessionDir, scopes);
+        const snapshot = buildSnapshot(input, key, before, projectScopes, indexed, previous);
+        if (before !== storeSignature(input.sessionDir, scopes))
+            continue;
+        if (before) {
+            cache.delete(key);
+            cache.set(key, snapshot);
+            while (cache.size > MAX_CACHED_SCOPES)
+                cache.delete(cache.keys().next().value);
+        }
+        return snapshot;
+    }
+    throw new Error("gli store di contesto stanno cambiando: snapshot coerente non disponibile");
+}
+function buildSnapshot(input, key, signature, projectScopes, indexed, previous) {
+    const pool = collectCandidates({ ...input, ...(projectScopes ? { projectScopes } : {}),
+        ...(indexed ? {} : { limit: 1000 }) });
+    const index = indexed ? new ContextSearchIndex(pool, previous?.index) : undefined;
+    // Eager capture: packet and candidates belong to the same checked revision.
+    const recent = new Map();
+    for (const candidate of pool)
+        if (candidate.scopeId)
+            recent.set(candidate.scopeId, Math.max(recent.get(candidate.scopeId) ?? 0, candidate.createdAt));
+    const packetScopes = projectScopes?.slice().sort((a, b) => (recent.get(b) ?? 0) - (recent.get(a) ?? 0) || a.localeCompare(b)).slice(0, 6);
+    const packet = buildMemoryPacket({ ...input, maxChars: Number.MAX_SAFE_INTEGER,
+        ...(packetScopes ? { projectScopes: packetScopes } : {}) });
+    const retrievals = new Map();
+    return {
+        key, signature, pool, ...(index ? { index } : {}),
+        packet: (maxChars) => clampMemoryPacket(packet, maxChars > 0 ? maxChars : 12_000),
+        retrieve(query, limit) {
+            const key = JSON.stringify([query, limit]);
+            const cached = retrievals.get(key);
+            if (cached)
+                return cached;
+            const ranked = retrieve(pool, { query, limit, ...(index ? { index } : { legacy: true }) });
+            if (retrievals.size >= 64)
+                retrievals.delete(retrievals.keys().next().value);
+            retrievals.set(key, ranked);
+            return ranked;
+        },
+    };
+}
+export function invalidateContextSnapshots() { cache.clear(); clearContextScopeIndexes(); }

package/dist/vascend/context-window-compiler.d.ts

@@ -0,0 +1,42 @@
+import { type ContextStoreSnapshot } from "./context-snapshot.js";
+import { type ScoreWeights, type TierThresholds } from "./context-scorer.js";
+import { type ContextScore } from "./context-candidate.js";
+import { type BudgetPolicy } from "./budget-allocator.js";
+import { type LintReport } from "./context-lint.js";
+import { type ContextMetrics } from "./context-metrics.js";
+import { type ContextRegret } from "./context-regret.js";
+import type { MarketResult } from "./token-market.js";
+export { selectWithMarket, type MarketSelection, type MarketSelectionInput } from "./context-market-selection.js";
+export interface CompileInput {
+    readonly planScopeId?: string;
+    readonly sessionDir: string;
+    readonly scopeId: string;
+    readonly projectKey?: string;
+    readonly userText: string;
+    readonly retrievalQuery?: string;
+    readonly totalTokens?: number;
+    readonly policy?: BudgetPolicy;
+    readonly now?: number;
+    readonly goal?: string;
+    readonly constraints?: readonly string[];
+    readonly success?: string;
+    readonly nextAction?: string;
+    readonly recallBlock?: string;
+    readonly toolBlock?: string;
+    readonly visionBlock?: string;
+    readonly weights?: ScoreWeights;
+    readonly thresholds?: TierThresholds;
+    readonly snapshot?: ContextStoreSnapshot;
+    readonly proofChains?: boolean;
+    readonly capsuleMarket?: boolean;
+}
+export interface CompiledContext {
+    readonly pack: string;
+    readonly report: LintReport;
+    readonly selected: readonly ContextScore[];
+    readonly tokensUsed: number;
+    readonly metrics: ContextMetrics;
+    readonly regret: ContextRegret;
+    readonly market?: MarketResult;
+}
+export declare function compileContext(input: CompileInput): CompiledContext;

package/dist/vascend/context-window-compiler.js

@@ -0,0 +1,237 @@
+// Context Window Compiler (metodo Danilov, Memory OS) -- L1.
+//
+// Il salto sopra il Memory Packet: non manda "piu' memoria", ma COMPILA la
+// forma ottimale del prompt per il turno. Orchestratore deterministico della
+// pipeline:
+//
+//   collect  -> raccoglie i candidati dagli store (candidate-collector)
+//   retrieve -> ranking ibrido BM25 + link graph, drop superseded (context-retriever)
+//   score    -> scoring multi-fattore + tier HIGH/MID/LOW (context-scorer)
+//   budget   -> alloca token per zona, packing greedy (budget-allocator)
+//   lint     -> dedup, stale, conflitti, budget (context-lint)
+//   layout   -> zone 1-9 con mission/tail anchor anti-rot (attention-layout)
+//
+// Output: un Prompt Pack (stringa) + il report, da anteporre come blocco system.
+//
+// Modulo di SOLA LETTURA verso gli store (via collector). Nessuna scrittura.
+import { loadContextStoreSnapshot } from "./context-snapshot.js";
+import { scoreCandidate, } from "./context-scorer.js";
+import {} from "./context-candidate.js";
+import { allocateBudget, clampToBudget, estimateTokens, } from "./budget-allocator.js";
+import { assembleLayout, layoutOverheadTokens, buildMissionAnchor, buildTailAnchor, } from "./attention-layout.js";
+import { lintContext } from "./context-lint.js";
+import { planRecall, formatRecallPlan, RECALL_FIRST_POLICY } from "./recall-planner.js";
+import { computeContextMetrics } from "./context-metrics.js";
+import { buildProofChain, renderProofChain, isContinuationRequest } from "./proof-chains.js";
+import { computeContextRegret } from "./context-regret.js";
+import { renderCapsules } from "./expansion-levels.js";
+import { selectWithMarket } from "./context-market-selection.js";
+import { packRendered, renderControlLane, renderEvidence, renderHandle, HANDLE_GUIDE, remainingTokens, joinBlocks } from "./context-pack-render.js";
+// Mantiene l'entry point SDK esistente per i caller della selezione pura.
+export { selectWithMarket } from "./context-market-selection.js";
+const DEFAULT_TOTAL = 3_000;
+// Compila la context window del turno. Deterministico a parita' di store + now.
+export function compileContext(input) {
+    const now = input.now ?? Date.now();
+    const total = input.totalTokens !== undefined && Number.isFinite(input.totalTokens)
+        ? Math.max(0, Math.floor(input.totalTokens)) : DEFAULT_TOTAL;
+    // Il turno utente viaggia nella cronologia, fuori dal pack: sottrarlo qui
+    // azzerava la memoria proprio sulle richieste lunghe. Gli header invece
+    // appartengono al pack e vanno riservati prima di allocare le zone.
+    const overhead = layoutOverheadTokens(["mission", "vision", "memory", "evidence", "recall", "tool", "tail"]);
+    const alloc = allocateBudget({
+        totalTokens: Math.max(0, total - overhead),
+        ...(input.policy ? { policy: input.policy } : {}),
+    });
+    // 1) collect + 2) retrieve (drop superseded incluso). Entrambi vengono dallo
+    // snapshot degli store: dentro un turno il disco viene letto una volta sola.
+    const snapshot = input.snapshot ?? loadContextStoreSnapshot({
+        sessionDir: input.sessionDir,
+        scopeId: input.scopeId,
+        ...(input.planScopeId ? { planScopeId: input.planScopeId } : {}),
+        ...(input.projectKey ? { projectKey: input.projectKey } : {}),
+    });
+    const retrievalQuery = input.retrievalQuery?.trim() || input.userText;
+    const recallPlan = planRecall({ userText: input.userText, recallBudget: alloc.recall });
+    const retrievedRanked = snapshot.retrieve(retrievalQuery, 40);
+    const materializedRecall = recallPlan.needed
+        ? snapshot.retrieve(`${recallPlan.query}\n${retrievalQuery}`.trim(), 24)
+            .filter((item) => !recallPlan.domains.length || recallPlan.domains.includes(item.candidate.domain))
+            .map((item) => item.candidate)
+        : [];
+    // Control lane autoritativa: goal/task aperti/decisioni/vision non possono
+    // dipendere dal fatto che la query corrente ripeta le stesse parole.
+    const mandatory = controlLaneCandidates(snapshot.pool, Boolean(input.nextAction));
+    const retrieved = mergeCandidates(mandatory, materializedRecall, retrievedRanked.map((r) => r.candidate));
+    const hasActiveDecisions = snapshot.pool.some((candidate) => candidate.kind === "decision" && candidate.status === "active" && !candidate.supersededBy);
+    // Conserva il segnale ibrido gia' calcolato dal retriever: BM25 per i match
+    // diretti, rilevanza propagata per prerequisiti e prove collegate. Lo
+    // normalizziamo sul batch prima dello scoring multi-fattore.
+    const maxRetrieval = retrievedRanked.reduce((max, item) => (item.retrievalScore > max ? item.retrievalScore : max), 0);
+    const retrievalScores = new Map();
+    if (maxRetrieval > 0) {
+        for (const item of retrievedRanked) {
+            retrievalScores.set(item.candidate.id, item.retrievalScore / maxRetrieval);
+        }
+    }
+    // 3) score con novelty incrementale. Se il chiamante passa pesi/soglie
+    //    adattati dall'autotuner, l'anello di retroazione li applica qui.
+    const ctx = {
+        query: retrievalQuery,
+        now,
+        tokenBudget: alloc.evidence + alloc.memory,
+        ...(retrievalScores.size ? { retrievalScores } : {}),
+        ...(input.weights ? { weights: input.weights } : {}),
+        ...(input.thresholds ? { thresholds: input.thresholds } : {}),
+    };
+    // La pulizia precede tutte le corsie, anche control lane e proof chain.
+    const validity = lintContext({ selected: retrieved });
+    const validIds = new Set(validity.cleaned.map((candidate) => candidate.id));
+    const scored = scoreCandidatesWithNovelty(validity.cleaned, ctx);
+    const cleanMandatory = mandatory.filter((candidate) => validIds.has(candidate.id));
+    // 4) Riserva i prefissi PRIMA della selezione: packet e control lane non
+    // possono consumare una seconda volta i token gia' venduti alle capsule.
+    const control = renderControlLane(cleanMandatory, Math.floor(alloc.memory * 0.35));
+    const packetBudget = Math.floor(alloc.memory * 0.35);
+    const packet = packetBudget > 0
+        ? clampToBudget(snapshot.packet(packetBudget * 4), packetBudget) : "";
+    const memoryBase = joinBlocks(control.text, packet);
+    const memoryBudget = remainingTokens(alloc.memory, memoryBase);
+    let proofChainBlock = "";
+    let proofCandidates = [];
+    if (input.proofChains && isContinuationRequest(input.userText)) {
+        const chain = buildProofChain(scored.filter((score) => score.tier !== "low").map((score) => score.candidate), {
+            ...(input.goal ? { goal: input.goal } : {}),
+            ...(input.nextAction ? { nextAction: input.nextAction } : {}),
+        });
+        if (chain) {
+            const rendered = renderProofChain(chain);
+            // Una catena parziale perde i legami causali: entra intera o lascia
+            // spazio alle singole prove e ai relativi handle.
+            if (estimateTokens(rendered) <= Math.floor(alloc.evidence * 0.4)) {
+                proofChainBlock = rendered;
+                const ids = new Set(chain.links.flatMap((link) => link.id ? [link.id] : []));
+                proofCandidates = validity.cleaned.filter((candidate) => ids.has(candidate.id));
+            }
+        }
+    }
+    const evidenceBudget = remainingTokens(alloc.evidence, proofChainBlock);
+    let evidenceText = "";
+    let memoryText = "";
+    let evidenceCandidates = [];
+    let memoryCandidates = [];
+    let market;
+    if (input.capsuleMarket) {
+        const selection = selectWithMarket({
+            scored,
+            ...(retrievalScores.size ? { retrievalScores } : {}),
+            evidenceBudget, memoryBudget, now,
+        });
+        market = selection.market;
+        const byId = new Map(scored.map((score) => [score.candidate.id, score.candidate]));
+        evidenceCandidates = selection.evidence.map((capsule) => byId.get(capsule.header.id));
+        memoryCandidates = selection.memory.map((capsule) => byId.get(capsule.header.id));
+        evidenceText = renderCapsules(selection.evidence);
+        memoryText = renderCapsules(selection.memory);
+    }
+    else {
+        const high = scored.filter((score) => score.tier === "high").map((score) => score.candidate);
+        const evidence = packRendered(high, renderEvidence, evidenceBudget);
+        const overflowIds = new Set(evidence.excluded.map((candidate) => candidate.id));
+        // Conserva l'ordine dello scorer anche dopo il degrado: una prova HIGH
+        // esclusa per dimensione precede gli handle MID meno rilevanti.
+        const handles = scored.filter((score) => score.tier === "mid" || overflowIds.has(score.candidate.id))
+            .map((score) => score.candidate);
+        const memory = packRendered(handles, renderHandle, memoryBudget, { before: HANDLE_GUIDE });
+        evidenceCandidates = evidence.included;
+        memoryCandidates = memory.included;
+        evidenceText = evidence.text;
+        memoryText = memory.text;
+    }
+    // La ricevuta descrive SOLO record integri resi, incluse le corsie di
+    // controllo e le citazioni nella proof chain. Il packet L0 e' orientamento
+    // testuale separato, non una prova contabilizzata per candidato.
+    const renderedCandidates = mergeCandidates(control.included, proofCandidates, evidenceCandidates, memoryCandidates);
+    const activeDecisions = renderedCandidates.filter((candidate) => candidate.kind === "decision")
+        .map((candidate) => candidate.summary).slice(0, 4);
+    const goal = input.goal ?? input.userText;
+    const autoRecall = recallPlan.needed
+        ? `${formatRecallPlan(recallPlan)}\n@recall[materializzato]: ${materializedRecall.length} candidati caricati prima della chiamata\n\n${RECALL_FIRST_POLICY}`
+        : RECALL_FIRST_POLICY;
+    // 5) Layout: ogni zona e' gia' entro budget, inclusi separatori interni.
+    const content = {
+        mission: buildMissionAnchor({
+            goal,
+            ...(input.constraints ? { constraints: input.constraints } : {}),
+            ...(input.success ? { success: input.success } : {}),
+        }, alloc.mission),
+        ...(input.visionBlock ? { vision: clampToBudget(input.visionBlock, alloc.vision) } : {}),
+        memory: joinBlocks(memoryBase, memoryText),
+        evidence: joinBlocks(proofChainBlock, evidenceText),
+        recall: clampToBudget(input.recallBlock ?? autoRecall, alloc.recall),
+        ...(input.toolBlock ? { tool: clampToBudget(input.toolBlock, alloc.tool) } : {}),
+        tail: buildTailAnchor({
+            goal,
+            ...(input.constraints ? { constraints: input.constraints } : {}),
+            ...(activeDecisions.length ? { activeDecisions } : {}),
+            ...(input.nextAction ? { nextAction: input.nextAction } : {}),
+            recallPolicy: true,
+        }, alloc.tail),
+    };
+    // Nessun taglio dopo il rendering: non puo' invalidare record e ricevuta.
+    const pack = assembleLayout(content);
+    const finalLint = lintContext({
+        selected: renderedCandidates,
+        tokenBudget: total,
+        renderedTokens: estimateTokens(pack),
+        hasVision: Boolean(content.vision) || renderedCandidates.some((candidate) => candidate.domain === "vision"),
+        hasActiveDecisions,
+    });
+    const report = {
+        ...finalLint,
+        findings: [...validity.findings, ...finalLint.findings],
+        ok: validity.ok && finalLint.ok,
+    };
+    const includedIds = new Set(report.cleaned.map((candidate) => candidate.id));
+    const evidenceIds = new Set(evidenceCandidates.map((candidate) => candidate.id));
+    const metrics = computeContextMetrics({ scored, pack, report, includedIds, evidenceIds });
+    const regret = computeContextRegret({
+        scored, report, metrics, includedIds,
+        recallPlannedButUnused: recallPlan.needed && !materializedRecall.some((candidate) => includedIds.has(candidate.id)),
+    });
+    return {
+        pack, report, selected: scored, tokensUsed: estimateTokens(pack), metrics, regret,
+        ...(market ? { market } : {}),
+    };
+}
+function controlLaneCandidates(pool, includeTasks) {
+    const active = pool.filter((candidate) => candidate.status === "active" && !candidate.supersededBy);
+    const sorted = (items, limit) => [...items].sort((a, b) => b.createdAt - a.createdAt || a.id.localeCompare(b.id)).slice(0, limit);
+    return mergeCandidates(includeTasks ? sorted(active.filter((candidate) => candidate.kind === "task" && candidate.dependency), 10) : [], sorted(active.filter((candidate) => candidate.kind === "decision"), 6), sorted(active.filter((candidate) => candidate.domain === "vision"), 3), sorted(active.filter((candidate) => candidate.dependency && candidate.kind !== "task" && candidate.kind !== "decision"), 5)).slice(0, 20);
+}
+function mergeCandidates(...groups) {
+    const seen = new Set();
+    const out = [];
+    for (const group of groups) {
+        for (const candidate of group) {
+            if (seen.has(candidate.id))
+                continue;
+            seen.add(candidate.id);
+            out.push(candidate);
+        }
+    }
+    return out;
+}
+// Scoring con novelty incrementale (penalizza i simili ai gia' accettati).
+function scoreCandidatesWithNovelty(candidates, ctx) {
+    const base = candidates.map((c) => scoreCandidate(c, ctx)).sort((a, b) => b.score - a.score || a.candidate.id.localeCompare(b.candidate.id));
+    const seen = [];
+    const out = [];
+    for (const s of base) {
+        const rescored = scoreCandidate(s.candidate, ctx, { seenTermSets: seen });
+        out.push(rescored);
+        if (rescored.tier !== "low")
+            seen.push(new Set(s.candidate.terms));
+    }
+    return out.sort((a, b) => b.score - a.score || a.candidate.id.localeCompare(b.candidate.id));
+}

package/dist/vascend/contract-memory.d.ts

@@ -0,0 +1,61 @@
+import type { Message } from "../core/types.js";
+import type { RoomRecord } from "./room-memory.js";
+export interface ContractEvent {
+    readonly type: "contract.changed";
+    readonly domain: "contracts";
+    readonly id: string;
+    readonly symbol: string;
+    readonly before: string;
+    readonly after: string;
+    readonly kind: ContractChangeKind;
+    readonly callsites: readonly string[];
+    readonly testsRequired: readonly string[];
+    readonly docsToUpdate: readonly string[];
+    readonly context: string;
+    readonly task: string | null;
+    readonly subject: string;
+    readonly summary: string;
+    readonly source: "user" | "assistant";
+    readonly createdAt: number;
+}
+export type ContractChangeKind = "signature" | "rename" | "remove" | "add" | "behavior";
+export interface ContractMatch {
+    readonly symbol: string;
+    readonly before: string;
+    readonly after: string;
+    readonly kind: ContractChangeKind;
+    readonly context: string;
+    readonly source: "user" | "assistant";
+}
+export declare function detectContractChanges(text: string, source: "user" | "assistant"): readonly ContractMatch[];
+export declare function extractImpacts(text: string): {
+    callsites: string[];
+    testsRequired: string[];
+    docsToUpdate: string[];
+};
+export declare function promoteContractChanges(messages: readonly Message[], opts: {
+    task?: string | null;
+    ns?: string;
+    now: number;
+    startNum?: number;
+}): readonly ContractEvent[];
+export declare function contractToRoomRecord(ev: ContractEvent): RoomRecord;
+export interface ContractSearchHit {
+    readonly event: ContractEvent;
+    readonly score: number;
+}
+export declare class ContractStore {
+    private readonly file;
+    private events;
+    private constructor();
+    static open(sessionDir: string, storeId: string): ContractStore;
+    count(): number;
+    all(): readonly ContractEvent[];
+    nextNum(ns?: string): number;
+    append(event: ContractEvent): boolean;
+    appendAll(events: readonly ContractEvent[]): readonly ContractEvent[];
+    byTask(task: string): readonly ContractEvent[];
+    bySymbol(symbol: string): readonly ContractEvent[];
+    search(query: string, limit?: number): readonly ContractSearchHit[];
+    indexBlock(): string;
+}