@vascend/talos 0.1.0

package/dist/vascend/patch-plan-store.d.ts

@@ -0,0 +1,33 @@
+import { type PatchPlan, type PatchPlanDraft, type PatchPlanStatus, type TestStatus } from "./patch-plan.js";
+export declare class VascendPatchPlanStore {
+    private readonly file;
+    private readonly memory;
+    private plans;
+    private seq;
+    private constructor();
+    static open(sessionDir: string, sessionId: string): VascendPatchPlanStore;
+    has(planId: string): boolean;
+    get(planId: string): PatchPlan | undefined;
+    all(): readonly PatchPlan[];
+    list(status?: PatchPlanStatus): readonly PatchPlan[];
+    nextId(): string;
+    create(draft: PatchPlanDraft, opts?: {
+        readonly now?: string;
+    }): PatchPlan;
+    update(planId: string, patch: Partial<Pick<PatchPlan, "goal" | "status" | "files" | "contracts" | "risks" | "tests" | "taskRef">>, opts?: {
+        readonly now?: string;
+    }): PatchPlan | undefined;
+    private transition;
+    approve(planId: string): PatchPlan | undefined;
+    markApplied(planId: string): PatchPlan | undefined;
+    abandon(planId: string): PatchPlan | undefined;
+    recordTest(planId: string, testId: string, status: TestStatus, text?: string): PatchPlan | undefined;
+    markVerified(planId: string): PatchPlan | undefined;
+    remove(planId: string): boolean;
+    clear(): void;
+    recall(query: string, limit?: number): readonly PatchPlan[];
+    private save;
+    private persist;
+}
+export { buildPatchPlanBlock, createPatchPlan, isPatchPlanValid, parsePatchPlan, patchPlanSummary, patchPlanToJSON, patchPlanVerification, validatePatchPlan, } from "./patch-plan.js";
+export type { PatchContract, PatchFile, PatchPlan, PatchPlanDraft, PatchPlanStatus, PatchRisk, PatchTest, } from "./patch-plan.js";

package/dist/vascend/patch-plan-store.js

@@ -0,0 +1,240 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { MemoryStore } from "./memory-store.js";
+import { buildPatchPlanBlock, createPatchPlan, parsePatchPlan, patchPlanSummary, patchPlanToJSON, patchPlanVerification, updatePatchPlan, validatePatchPlan, } from "./patch-plan.js";
+// VascendPatchPlanStore: persiste i Patch Plan per sessione e li proietta sul
+// MemoryStore (dominio "patches") cosi' che siano richiamabili via recall. Si
+// inserisce nel flusso analisi-repo -> recall -> [PATCH PLAN] -> edit -> verify:
+//
+//   create()        l'agente, prima di editare, dichiara il piano (status draft)
+//   approve()       il piano e' pronto: si puo' editare (status approved)
+//   markApplied()   l'edit e' stato fatto (status applied)
+//   recordTest()    si registra l'esito di un test (passed/failed)
+//   markVerified()  tutti i test passati: la patch e' verificata (status verified)
+//   abandon()       il piano e' scartato (status abandoned)
+//
+// File `<sessionId>.patches.json` -> mappa { [planId]: PatchPlan }. Stesso stile
+// di VascendPlanStore/VascendVisionStore: API immutabile, persistenza su
+// mutazione, eventi append-only sul MemoryStore.
+export class VascendPatchPlanStore {
+    file;
+    memory;
+    plans = {};
+    seq = 0;
+    constructor(file, memory) {
+        this.file = file;
+        this.memory = memory;
+    }
+    static open(sessionDir, sessionId) {
+        const store = new VascendPatchPlanStore(join(sessionDir, `${sessionId}.patches.json`), MemoryStore.open(sessionDir, sessionId));
+        if (existsSync(store.file)) {
+            try {
+                const raw = JSON.parse(readFileSync(store.file, "utf8"));
+                const out = {};
+                for (const [planId, val] of Object.entries(raw ?? {})) {
+                    const parsed = parsePatchPlan(JSON.stringify(val));
+                    if (parsed)
+                        out[planId] = { ...parsed, id: parsed.id || planId };
+                }
+                store.plans = out;
+                store.seq = highestSeq(Object.keys(out));
+            }
+            catch {
+                // file corrotto: si riparte vuoti
+            }
+        }
+        return store;
+    }
+    // --- lettura ----------------------------------------------------------
+    has(planId) {
+        return Boolean(this.plans[planId.trim()]);
+    }
+    get(planId) {
+        return this.plans[planId.trim()];
+    }
+    all() {
+        return Object.values(this.plans);
+    }
+    // Tutti i piani in un dato stato (es. "draft"/"applied"), per la dashboard
+    // del flusso (cosa resta da verificare).
+    list(status) {
+        const out = Object.values(this.plans);
+        return status ? out.filter((p) => p.status === status) : out;
+    }
+    // Genera un id "P<n>" libero (progressivo, non in uso).
+    nextId() {
+        let n = this.seq + 1;
+        while (this.plans[`P${n}`])
+            n += 1;
+        return `P${n}`;
+    }
+    // --- creazione + ciclo di vita ---------------------------------------
+    // Crea e persiste un nuovo Patch Plan da un draft. Se manca l'id ne genera uno.
+    // Status iniziale "draft" salvo diverso. Ritorna il piano salvato.
+    create(draft, opts) {
+        const id = (draft.id ?? "").trim() || this.nextId();
+        const plan = createPatchPlan({ ...draft, id, status: draft.status ?? "draft" }, opts);
+        return this.save(plan, "patch.plan.created");
+    }
+    // Aggiorna immutabilmente un piano con una patch parziale. No-op (undefined)
+    // se non esiste.
+    update(planId, patch, opts) {
+        const cur = this.plans[planId.trim()];
+        if (!cur)
+            return undefined;
+        return this.save(updatePatchPlan(cur, patch, opts), "patch.plan.updated");
+    }
+    // Transizione di stato sicura (draft->approved->applied->verified, o abandoned).
+    // No-op se il piano non esiste.
+    transition(planId, status, type) {
+        const cur = this.plans[planId.trim()];
+        if (!cur)
+            return undefined;
+        return this.save(updatePatchPlan(cur, { status }), type);
+    }
+    approve(planId) {
+        return this.transition(planId, "approved", "patch.plan.approved");
+    }
+    markApplied(planId) {
+        return this.transition(planId, "applied", "patch.plan.applied");
+    }
+    abandon(planId) {
+        return this.transition(planId, "abandoned", "patch.plan.abandoned");
+    }
+    // Registra l'esito di un test del piano (per id del test). Se l'id non esiste
+    // viene aggiunto. Ritorna il piano aggiornato o undefined se il piano manca.
+    recordTest(planId, testId, status, text) {
+        const cur = this.plans[planId.trim()];
+        if (!cur)
+            return undefined;
+        const tid = testId.trim();
+        let found = false;
+        const tests = cur.tests.map((t) => {
+            if (t.id.toLowerCase() === tid.toLowerCase()) {
+                found = true;
+                return { ...t, status, ...(text ? { text } : {}) };
+            }
+            return t;
+        });
+        if (!found)
+            tests.push({ id: tid || `T${cur.tests.length + 1}`, text: text ?? tid, status });
+        return this.save(updatePatchPlan(cur, { tests }), "patch.plan.test");
+    }
+    // Marca il piano "verified" SOLO se tutti i suoi test sono passati (e ne
+    // esiste almeno uno). Se i test non sono tutti passati ritorna il piano
+    // invariato (non lo promuove). Undefined se il piano non esiste.
+    markVerified(planId) {
+        const cur = this.plans[planId.trim()];
+        if (!cur)
+            return undefined;
+        if (!patchPlanVerification(cur).verified)
+            return cur;
+        return this.transition(planId, "verified", "patch.plan.verified");
+    }
+    remove(planId) {
+        const id = planId.trim();
+        if (!this.plans[id])
+            return false;
+        const { [id]: _drop, ...rest } = this.plans;
+        this.plans = rest;
+        this.persist();
+        this.memory.append({
+            type: "patch.plan.removed",
+            domain: "patches",
+            subject: id,
+            summary: `Patch Plan rimosso: ${id}`,
+            body: "",
+            terms: [id, "patch", "plan", "rimosso"],
+            payload: { planId: id },
+        });
+        return true;
+    }
+    clear() {
+        this.plans = {};
+        this.seq = 0;
+        try {
+            if (existsSync(this.file))
+                rmSync(this.file);
+        }
+        catch {
+            // best effort
+        }
+    }
+    // --- recall + persistenza --------------------------------------------
+    // Recupera i piani richiamabili via ricerca testuale sul MemoryStore (vista
+    // derivata dal dominio "patches"). Ritorna i piani corrispondenti agli eventi
+    // trovati, piu' recenti prima, deduplicati per id.
+    recall(query, limit = 5) {
+        const hits = this.memory.search(query, { domain: "patches", limit: limit * 3 });
+        const seen = new Set();
+        const out = [];
+        for (const hit of hits) {
+            const planId = String(hit.event.payload?.plan?.id ?? hit.event.subject).trim();
+            if (!planId || seen.has(planId))
+                continue;
+            seen.add(planId);
+            const plan = this.plans[planId];
+            if (plan)
+                out.push(plan);
+            if (out.length >= limit)
+                break;
+        }
+        return out;
+    }
+    save(plan, type) {
+        const id = plan.id.trim();
+        this.plans = { ...this.plans, [id]: { ...plan, id } };
+        this.seq = Math.max(this.seq, seqOf(id));
+        this.persist();
+        this.memory.append(patchEvent(type, this.plans[id]));
+        return this.plans[id];
+    }
+    persist() {
+        mkdirSync(dirname(this.file), { recursive: true });
+        const ordered = {};
+        for (const [id, p] of Object.entries(this.plans)) {
+            ordered[id] = JSON.parse(patchPlanToJSON(p));
+        }
+        writeFileSync(this.file, JSON.stringify(ordered, null, 2) + "\n", "utf8");
+    }
+}
+// --- helper interni -----------------------------------------------------
+function seqOf(id) {
+    const m = /^P(\d+)$/i.exec(id.trim());
+    return m ? Number(m[1]) : 0;
+}
+function highestSeq(ids) {
+    return ids.reduce((max, id) => Math.max(max, seqOf(id)), 0);
+}
+// Evento di memoria per un Patch Plan: indicizzato sui termini di goal, file,
+// contratti, rischi e test cosi' che recall lo trovi per qualunque di questi.
+function patchEvent(type, plan) {
+    const sum = patchPlanSummary(plan);
+    const terms = [
+        plan.id,
+        plan.status,
+        ...plan.goal.split(/\s+/),
+        ...plan.files.flatMap((f) => [f.path, f.kind]),
+        ...plan.contracts.flatMap((c) => [c.id, c.name, c.impact]),
+        ...plan.risks.flatMap((r) => [r.id, r.severity]),
+        ...plan.tests.flatMap((t) => [t.id, t.status]),
+        "patch", "plan",
+    ];
+    return {
+        type,
+        domain: "patches",
+        subject: plan.id,
+        summary: `[${plan.status}] ${plan.goal}`,
+        body: buildPatchPlanBlock(plan),
+        terms,
+        links: [
+            ...(plan.taskRef ? [{ rel: "for", target: plan.taskRef, domain: "plan" }] : []),
+            ...plan.files.map((f) => ({ rel: "touches", target: f.path, domain: "files" })),
+            ...plan.contracts.map((c) => ({ rel: c.impact, target: c.name, domain: "patches" })),
+            ...plan.tests.map((t) => ({ rel: "verified_by", target: t.id, domain: "patches" })),
+        ],
+        payload: { plan, summary: sum },
+    };
+}
+// Riesporta il modello per comodita' dei consumatori (un solo import).
+export { buildPatchPlanBlock, createPatchPlan, isPatchPlanValid, parsePatchPlan, patchPlanSummary, patchPlanToJSON, patchPlanVerification, validatePatchPlan, } from "./patch-plan.js";

package/dist/vascend/patch-plan.d.ts

@@ -0,0 +1,97 @@
+export type PatchPlanStatus = "draft" | "approved" | "applied" | "verified" | "abandoned";
+export type RiskSeverity = "low" | "medium" | "high";
+export type TestStatus = "pending" | "passed" | "failed";
+export type FileChangeKind = "create" | "modify" | "delete" | "rename";
+export interface PatchFile {
+    readonly path: string;
+    readonly kind: FileChangeKind;
+    readonly reason?: string;
+}
+export interface PatchContract {
+    readonly id: string;
+    readonly name: string;
+    readonly impact: "uses" | "changes" | "breaks";
+    readonly note?: string;
+}
+export interface PatchRisk {
+    readonly id: string;
+    readonly text: string;
+    readonly severity: RiskSeverity;
+    readonly mitigation?: string;
+}
+export interface PatchTest {
+    readonly id: string;
+    readonly text: string;
+    readonly status: TestStatus;
+}
+export interface PatchPlan {
+    readonly version: 1;
+    readonly id: string;
+    readonly taskRef?: string;
+    readonly goal: string;
+    readonly status: PatchPlanStatus;
+    readonly files: readonly PatchFile[];
+    readonly contracts: readonly PatchContract[];
+    readonly risks: readonly PatchRisk[];
+    readonly tests: readonly PatchTest[];
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export interface PatchPlanDraft {
+    readonly id?: string;
+    readonly taskRef?: string;
+    readonly goal: string;
+    readonly status?: PatchPlanStatus;
+    readonly files?: ReadonlyArray<Partial<PatchFile> & {
+        readonly path: string;
+    }>;
+    readonly contracts?: ReadonlyArray<Partial<PatchContract> & {
+        readonly name: string;
+    }>;
+    readonly risks?: ReadonlyArray<Partial<PatchRisk> & {
+        readonly text: string;
+    }>;
+    readonly tests?: ReadonlyArray<Partial<PatchTest> & {
+        readonly text: string;
+    }>;
+}
+export declare const PATCH_PLAN_SCHEMA_VERSION: 1;
+export interface PatchPlanIssue {
+    readonly field: string;
+    readonly message: string;
+}
+export declare function validatePatchPlan(p: PatchPlan): readonly PatchPlanIssue[];
+export declare function isPatchPlanValid(p: PatchPlan): boolean;
+export declare function createPatchPlan(draft: PatchPlanDraft, opts?: {
+    readonly now?: string;
+    readonly id?: string;
+}): PatchPlan;
+export declare function parsePatchPlan(text: string, opts?: {
+    readonly now?: string;
+}): PatchPlan | null;
+export declare function updatePatchPlan(p: PatchPlan, patch: Partial<Pick<PatchPlan, "goal" | "status" | "files" | "contracts" | "risks" | "tests" | "taskRef">>, opts?: {
+    readonly now?: string;
+}): PatchPlan;
+export declare function patchPlanToJSON(p: PatchPlan): string;
+export declare function patchPlanFromJSON(json: string, opts?: {
+    readonly now?: string;
+}): PatchPlan | null;
+export interface PatchPlanSummary {
+    readonly files: number;
+    readonly contracts: number;
+    readonly breakingContracts: number;
+    readonly risks: number;
+    readonly highRisks: number;
+    readonly tests: number;
+    readonly testsPassed: number;
+}
+export declare function patchPlanSummary(p: PatchPlan): PatchPlanSummary;
+export interface PatchPlanVerification {
+    readonly ratio: number;
+    readonly verified: boolean;
+    readonly testsPassed: number;
+    readonly testsTotal: number;
+    readonly testsFailed: number;
+}
+export declare function patchPlanVerification(p: PatchPlan): PatchPlanVerification;
+export declare function buildPatchPlanBlock(p: PatchPlan): string;