@vascend/talos 0.1.0

package/dist/vascend/ramification-store.js

@@ -0,0 +1,94 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createRoadmap, } from "./ramification.js";
+// Persistenza del piano a rami. Un task a orizzonte lungo dura piu' di una
+// sessione: il piano non puo' vivere in una finestra di contesto, sta su disco
+// accanto agli altri store della sessione e ogni sessione nuova lo riapre e
+// riparte dalla frontiera.
+//
+// Il file e' per CONVERSAZIONE, non per sessione singola: e' la stessa scelta
+// del taccuino, e per lo stesso motivo — quello che il team decide al nodo 3
+// deve esistere ancora al nodo 40, in una sessione che allora non c'era.
+const VERSION = 1;
+function isRoadmap(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return typeof candidate.goal === "string"
+        && Array.isArray(candidate.branches)
+        && Array.isArray(candidate.log)
+        && typeof candidate.nodes === "object"
+        && candidate.nodes !== null;
+}
+export class RamificationStore {
+    file;
+    roadmap = null;
+    constructor(file) {
+        this.file = file;
+    }
+    static open(sessionDir, scope) {
+        const nome = String(scope || "default").replace(/[^A-Za-z0-9_.-]+/g, "-").slice(0, 80) || "default";
+        const store = new RamificationStore(join(sessionDir, `${nome}.ramification.json`));
+        if (existsSync(store.file)) {
+            try {
+                const raw = JSON.parse(readFileSync(store.file, "utf8"));
+                if (raw && isRoadmap(raw.roadmap)) {
+                    // Proposte e canale fra nodi sono arrivati dopo: un piano salvato
+                    // prima non deve esplodere alla riapertura, gli mancano solo due
+                    // elenchi vuoti. Le chiavi mancanti si riempiono DOPO lo spread,
+                    // altrimenti si sovrascriverebbero quelle salvate.
+                    const salvato = raw.roadmap;
+                    store.roadmap = {
+                        ...salvato,
+                        proposals: Array.isArray(salvato.proposals) ? salvato.proposals : [],
+                        crosstalk: Array.isArray(salvato.crosstalk) ? salvato.crosstalk : [],
+                    };
+                }
+            }
+            catch {
+                // File illeggibile: si riparte senza piano invece di perdere la sessione.
+            }
+        }
+        return store;
+    }
+    has() {
+        return this.roadmap !== null;
+    }
+    current() {
+        return this.roadmap;
+    }
+    // Crea il piano. Rifiuta di sovrascriverne uno esistente: un percorso lungo
+    // non si azzera per sbaglio con una chiamata che sembrava innocua.
+    create(input) {
+        if (this.roadmap) {
+            return { ok: false, reason: "esiste gia' un piano a rami per questa conversazione", roadmap: this.roadmap };
+        }
+        this.roadmap = createRoadmap(input);
+        this.persist();
+        return { ok: true, reason: "", roadmap: this.roadmap };
+    }
+    // Applica un'operazione pura del modello e persiste SOLO se e' andata a buon
+    // fine. Un rifiuto non deve lasciare il file a meta'.
+    apply(operazione) {
+        if (!this.roadmap)
+            return { ok: false, reason: "nessun piano a rami: creane uno prima", roadmap: null };
+        const esito = operazione(this.roadmap);
+        if (!esito.ok) {
+            // Anche il rifiuto lascia una traccia nel registro: il perche' di un "no"
+            // vale quanto il perche' di un "sì".
+            this.roadmap = esito.roadmap;
+            this.persist();
+            return { ok: false, reason: esito.reason, roadmap: this.roadmap };
+        }
+        this.roadmap = esito.roadmap;
+        this.persist();
+        return { ok: true, reason: "", roadmap: this.roadmap };
+    }
+    persist() {
+        if (!this.roadmap)
+            return;
+        const payload = { version: VERSION, roadmap: this.roadmap };
+        mkdirSync(dirname(this.file), { recursive: true });
+        writeFileSync(this.file, JSON.stringify(payload, null, 2) + "\n", "utf8");
+    }
+}

package/dist/vascend/ramification.d.ts

@@ -0,0 +1,193 @@
+export type NodeState = "locked" | "ready" | "running" | "review" | "committed" | "returned";
+export type Decision = "pass" | "return" | "replan";
+export interface NodeTransaction {
+    readonly artifact: string;
+    readonly tests: readonly string[];
+    readonly evidence: readonly string[];
+    readonly commit: string;
+    readonly at: number;
+}
+export interface Verdict {
+    readonly decision: Decision;
+    readonly by: string;
+    readonly reason: string;
+    readonly consulted?: readonly string[];
+    readonly at: number;
+}
+export interface Proposal {
+    readonly id: string;
+    readonly by: string;
+    readonly branch: string;
+    readonly reason: string;
+    readonly mutation: Mutation;
+    readonly state: "pending" | "accepted" | "rejected";
+    readonly at: number;
+}
+export interface RamNode {
+    readonly id: string;
+    readonly branch: string;
+    readonly title: string;
+    readonly mandate: string;
+    readonly acceptance: readonly string[];
+    readonly after: readonly string[];
+    readonly state: NodeState;
+    readonly sessionId?: string;
+    readonly transaction?: NodeTransaction;
+    readonly verdict?: Verdict;
+    readonly returns: number;
+}
+export interface Branch {
+    readonly id: string;
+    readonly owner: string;
+    readonly vision: string;
+    readonly nodes: readonly string[];
+}
+export type LogKind = "roadmap.created" | "branch.added" | "node.added" | "node.started" | "node.submitted" | "node.consulted" | "node.committed" | "node.returned" | "node.replan" | "mutation.proposed" | "mutation.rejected" | "future.mutated" | "refused";
+export interface LogEntry {
+    readonly kind: LogKind;
+    readonly by: string;
+    readonly subject: string;
+    readonly detail: string;
+    readonly at: number;
+}
+export interface CrossNodeMessage {
+    readonly seq: number;
+    readonly from: {
+        readonly node: string;
+        readonly branch: string;
+        readonly session: string;
+        readonly who: string;
+    };
+    readonly to: string;
+    readonly text: string;
+    readonly at: number;
+}
+export interface Roadmap {
+    readonly goal: string;
+    readonly acceptance: readonly string[];
+    readonly founders: readonly string[];
+    readonly branches: readonly Branch[];
+    readonly nodes: Readonly<Record<string, RamNode>>;
+    readonly proposals: readonly Proposal[];
+    readonly crosstalk: readonly CrossNodeMessage[];
+    readonly log: readonly LogEntry[];
+    readonly revision: number;
+}
+export interface Refusal {
+    readonly ok: false;
+    readonly reason: string;
+    readonly roadmap: Roadmap;
+}
+export interface Applied {
+    readonly ok: true;
+    readonly roadmap: Roadmap;
+}
+export type Outcome = Applied | Refusal;
+export declare function createRoadmap(input: {
+    readonly goal: string;
+    readonly acceptance?: readonly string[];
+    readonly founders?: readonly string[];
+    readonly at: number;
+}): Roadmap;
+export declare function addBranch(roadmap: Roadmap, input: {
+    readonly id: string;
+    readonly owner: string;
+    readonly vision: string;
+    readonly at: number;
+}): Outcome;
+export declare function addNode(roadmap: Roadmap, input: {
+    readonly id: string;
+    readonly branch: string;
+    readonly title: string;
+    readonly mandate: string;
+    readonly acceptance?: readonly string[];
+    readonly after?: readonly string[];
+    readonly by: string;
+    readonly at: number;
+}): Outcome;
+export declare function frontier(roadmap: Roadmap): readonly RamNode[];
+export declare function startNode(roadmap: Roadmap, input: {
+    readonly id: string;
+    readonly sessionId: string;
+    readonly by: string;
+    readonly at: number;
+}): Outcome;
+export declare function submitNode(roadmap: Roadmap, input: {
+    readonly id: string;
+    readonly transaction: NodeTransaction;
+    readonly by: string;
+    readonly at: number;
+}): Outcome;
+export declare function consultOnNode(roadmap: Roadmap, input: {
+    readonly id: string;
+    readonly who: string;
+    readonly question: string;
+    readonly by: string;
+    readonly at: number;
+}): Outcome;
+export declare function judgeNode(roadmap: Roadmap, input: {
+    readonly id: string;
+    readonly decision: Decision;
+    readonly reason: string;
+    readonly by: string;
+    readonly consulted?: readonly string[];
+    readonly at: number;
+}): Outcome;
+export interface Mutation {
+    readonly add?: readonly {
+        readonly id: string;
+        readonly branch: string;
+        readonly title: string;
+        readonly mandate: string;
+        readonly acceptance?: readonly string[];
+        readonly after?: readonly string[];
+    }[];
+    readonly drop?: readonly string[];
+    readonly retarget?: readonly {
+        readonly id: string;
+        readonly mandate?: string;
+        readonly acceptance?: readonly string[];
+        readonly after?: readonly string[];
+    }[];
+}
+export declare function proposeMutation(roadmap: Roadmap, input: {
+    readonly id: string;
+    readonly branch: string;
+    readonly mutation: Mutation;
+    readonly reason: string;
+    readonly by: string;
+    readonly at: number;
+}): Outcome;
+export declare function resolveProposal(roadmap: Roadmap, input: {
+    readonly id: string;
+    readonly accept: boolean;
+    readonly reason: string;
+    readonly by: string;
+    readonly at: number;
+}): Outcome;
+export declare function mutateFuture(roadmap: Roadmap, input: {
+    readonly mutation: Mutation;
+    readonly by: string;
+    readonly reason: string;
+    readonly at: number;
+}): Outcome;
+export declare function postAcrossNodes(roadmap: Roadmap, input: {
+    readonly fromNode: string;
+    readonly who: string;
+    readonly to?: string;
+    readonly text: string;
+    readonly at: number;
+}): Outcome;
+export declare function crosstalkFor(roadmap: Roadmap, input: {
+    readonly node: string;
+    readonly since?: number;
+}): readonly CrossNodeMessage[];
+export declare function renderCrosstalk(message: CrossNodeMessage): string;
+export declare function progress(roadmap: Roadmap): readonly {
+    readonly branch: string;
+    readonly owner: string;
+    readonly committed: number;
+    readonly total: number;
+    readonly current: string;
+    readonly blocked: readonly string[];
+}[];