@vascend/talos 0.1.0

package/dist/vascend/context-capsule.js

@@ -0,0 +1,133 @@
+// Context Capsule (metodo Danilov, Memory OS) -- L2: Packet Algebra.
+//
+// Il salto sopra ContextCandidate: invece di tenere separati Memory Packet,
+// Evidence Slot, Recall Handle, asset e decisione, ogni frammento di memoria
+// diventa una CAPSULA TIPIZZATA con header, summary, proof, body, recall handle,
+// metriche (tokenCost/utility/freshness) e lineage (supersedes/derivedFrom).
+//
+// Una capsula non e' "testo si'/testo no": e' una struttura che il compiler puo'
+// rendere a piu' LIVELLI DI ESPANSIONE (R0-R4, vedi expansion-levels):
+//
+//   L0/R0 = solo handle (id + come recuperarlo)
+//   L1/R1 = summary + metadata
+//   L2/R2 = summary + reason/proof breve
+//   L3/R3 = evidence slot (prova citabile)
+//   L4/R4 = body completo / raw
+//
+// Cosi' il compiler decide il LIVELLO ottimale per ogni capsula, non solo
+// HIGH/MID/LOW: una decisione puo' entrare come corpo, un asset come
+// summary+handle, una stanza come solo indice.
+//
+// Modulo PURO e DETERMINISTICO: solo tipi e helper, nessun side-effect, nessuna
+// rete. Si appoggia a ContextCandidate (context-candidate) come fonte canonica.
+import { estimateCandidateTokens, confidenceWeight, } from "./context-candidate.js";
+export const EXPANSION_LEVELS = [0, 1, 2, 3, 4];
+// Etichette umane dei livelli, per diagnostica/log.
+export const EXPANSION_LABEL = {
+    0: "handle",
+    1: "summary",
+    2: "summary+reason",
+    3: "evidence",
+    4: "body",
+};
+// --- costruzione da candidato -----------------------------------------------
+// Utilita' di default derivata dai segnali del candidato (deterministica):
+// trust pesa, una dipendenza o una decisione attiva alzano l'utilita'.
+function defaultUtility(c) {
+    let u = confidenceWeight(c.trust) * 0.6;
+    if (c.dependency)
+        u += 0.25;
+    if (c.kind === "decision" && c.status === "active")
+        u += 0.15;
+    if (c.status !== "active" || c.supersededBy)
+        u *= 0.4; // obsoleto vale meno
+    return clamp01(u);
+}
+// Freschezza di default: senza createdAt usa neutro 0.5; altrimenti decadimento
+// esponenziale con half-life di 3 giorni rispetto a `now`.
+function defaultFreshness(createdAt, now) {
+    if (!createdAt)
+        return 0.5;
+    const halfLife = 72 * 60 * 60 * 1000;
+    const age = Math.max(0, now - createdAt);
+    return clamp01(Math.pow(0.5, age / halfLife));
+}
+// Estrae un "reason" implicito dal corpo del candidato (prima frase utile) per
+// alimentare il livello R2 (summary+reason). Deterministico, best-effort.
+function extractReason(body, summary) {
+    const src = (body || summary || "").replace(/\s+/g, " ").trim();
+    if (!src)
+        return "";
+    const firstSentence = src.split(/(?<=[.!?])\s/)[0] ?? src;
+    return oneLine(firstSentence, 160);
+}
+// Costruisce una capsula da un ContextCandidate. Deterministico a parita' di
+// candidato + now. E' la porta d'ingresso del Packet Algebra: ogni candidato
+// del Memory OS puo' diventare una capsula senza perdita di informazione.
+export function capsuleFromCandidate(c, opts = {}) {
+    const now = opts.now ?? 0;
+    const tokenCost = estimateCandidateTokens(c, "body");
+    const utility = typeof opts.utility === "number" ? clamp01(opts.utility) : defaultUtility(c);
+    const freshness = defaultFreshness(c.createdAt, now || c.createdAt);
+    const reason = extractReason(c.body, c.summary);
+    return {
+        header: {
+            id: c.id,
+            domain: c.domain,
+            type: c.kind,
+            status: c.status,
+            confidence: c.trust,
+        },
+        summary: oneLine(c.summary, 180),
+        reason,
+        // proof: per le capsule "forti" (decisione/asset/evento canonico) usiamo il
+        // corpo come prova citabile; per le altre resta vuoto finche' non promosse.
+        proof: c.kind === "decision" || c.kind === "asset" ? oneLine(c.body || c.summary, 400) : "",
+        body: c.body,
+        terms: c.terms,
+        recall: {
+            domains: [c.domain],
+            ...(opts.recallQuery ? { query: opts.recallQuery } : c.terms.length ? { query: c.terms.slice(0, 4).join(" ") } : {}),
+            id: c.id,
+        },
+        metrics: { tokenCost, utility, freshness },
+        lineage: {
+            ...(c.supersededBy ? { supersededBy: c.supersededBy } : { supersededBy: null }),
+            createdAt: c.createdAt,
+        },
+        expansionLevel: opts.expansionLevel ?? 1,
+    };
+}
+// Versione batch: converte un insieme di candidati in capsule. Mantiene l'ordine.
+export function capsulesFromCandidates(candidates, opts = {}) {
+    return candidates.map((c) => capsuleFromCandidate(c, opts));
+}
+// Ritorna una nuova capsula con un diverso livello di espansione (immutabile).
+export function withExpansion(capsule, level) {
+    if (capsule.expansionLevel === level)
+        return capsule;
+    return { ...capsule, expansionLevel: level };
+}
+// Numero di confidenza in [0,1] per i tre livelli (ri-esportato per chi opera
+// sulle capsule senza passare dai candidati).
+export function confidenceWeightOf(confidence) {
+    return confidenceWeight(confidence);
+}
+// Vero se la capsula e' obsoleta (superseded/archived o con supersededBy).
+export function isStale(capsule) {
+    return (capsule.header.status !== "active" ||
+        Boolean(capsule.lineage.supersededBy));
+}
+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;
+}

package/dist/vascend/context-fabric.d.ts

@@ -0,0 +1,108 @@
+import { type VibeModeId, type VibeModeRoute, type VibeModeSelection, type VibeModeSpec } from "../core/vibe-modes.js";
+import type { BudgetPolicy } from "./budget-allocator.js";
+import type { ScoreWeights, TierThresholds } from "./context-scorer.js";
+export type ContextLeaseSource = "pinned" | "mission" | "turn" | "mode";
+export interface ContextLease {
+    readonly id: string;
+    readonly term: string;
+    readonly source: ContextLeaseSource;
+    readonly weight: number;
+    readonly createdTurn: number;
+    readonly expiresAfterTurn: number | null;
+}
+export interface ContextReceipt {
+    readonly generatedAt: number;
+    readonly epoch: number;
+    readonly mode: VibeModeId;
+    readonly routeConfidence: number;
+    readonly routeReasons: readonly string[];
+    readonly memoryScopeId: string;
+    readonly mission: string;
+    readonly retrievalQuery: string;
+    readonly focusTerms: readonly string[];
+    readonly contextBudget: number;
+    readonly proofChains: boolean;
+    readonly inherited: boolean;
+}
+export interface GoalRevision {
+    readonly turn: number;
+    readonly text: string;
+    readonly kind: "clarification" | "constraint";
+    readonly createdAt: number;
+}
+export interface GoalContract {
+    readonly epoch: number;
+    readonly objective: string;
+    readonly revisions: readonly GoalRevision[];
+    readonly constraints: readonly string[];
+    readonly successCriteria: readonly string[];
+    readonly updatedAt: number;
+}
+export interface ContextFrame {
+    readonly version: 1;
+    readonly owner: string;
+    readonly projectKey: string;
+    readonly epoch: number;
+    readonly turn: number;
+    readonly selection: VibeModeSelection;
+    readonly activeMode: VibeModeId;
+    readonly mission: string;
+    readonly contract?: GoalContract;
+    readonly leases: readonly ContextLease[];
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    readonly reset: boolean;
+    readonly receipt: ContextReceipt | null;
+}
+export interface ContextFabricInput {
+    readonly sessionDir: string;
+    readonly frameId: string;
+    readonly memoryScopeId: string;
+    readonly cwd: string;
+    readonly selection: VibeModeSelection;
+    readonly userText: string;
+    readonly inheritProjectFrame?: boolean;
+    readonly now?: number;
+}
+export interface ContextFabricCompileOptions {
+    readonly retrievalQuery: string;
+    readonly totalTokens: number;
+    readonly policy: BudgetPolicy;
+    readonly weights: ScoreWeights;
+    readonly thresholds: TierThresholds;
+    readonly goal: string;
+    readonly constraints: readonly string[];
+    readonly success: string;
+    readonly nextAction: string;
+    readonly proofChains: boolean;
+}
+export interface ContextFabricResult {
+    readonly frame: ContextFrame;
+    readonly route: VibeModeRoute;
+    readonly mode: VibeModeSpec;
+    readonly rawUserText: string;
+    readonly systemBlock: string;
+    readonly compile: ContextFabricCompileOptions;
+}
+export declare function contextProjectKey(cwd: string): string;
+export declare function contextFramePath(sessionDir: string, frameId: string): string;
+export declare function loadContextFrame(sessionDir: string, frameId: string, projectKey: string, inherit?: boolean): ContextFrame | null;
+export declare function listContextMemoryScopes(sessionDir: string, projectKey: string): readonly string[];
+export declare function buildContextFabric(input: ContextFabricInput): ContextFabricResult;
+export declare function updateContextPins(input: {
+    readonly sessionDir: string;
+    readonly frameId: string;
+    readonly cwd: string;
+    readonly add?: readonly string[];
+    readonly remove?: readonly string[];
+    readonly now?: number;
+}): ContextFrame | null;
+export declare function resetContextFrame(input: {
+    readonly sessionDir: string;
+    readonly frameId: string;
+    readonly cwd: string;
+    readonly selection?: VibeModeSelection;
+    readonly preservePins?: boolean;
+    readonly now?: number;
+}): ContextFrame;
+export declare function renderContextFrame(frame: ContextFrame | null): string;